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How to Use This Publication 



This publication provides a full description of the use of the IBM System/360 
Operating System utility programs. This publication assumes that the reader is familiar 
with IBM System/360 Operating System terms and concepts. 

Effective use of this publication requires an understanding of the following: 

• Organization of the publication as a whole. 

• Organization of each program description. 

• Use of special referencing aids that help you find the right utility program and the 
right example. 

• Required publications. 

• Related publications. 

• Notational conventions used to describe the syntax (or format) of utility control 
statements. 

These topics are discussed below. 

Organization of In addition to the preface you are now reading, a table of contents, a list of figures, 

the Publication and a list of tables, this publication has these major parts: 

• "Summary of Major Changes for Release 21.7," which is a summary of the major 
changes in this edition. 

• "Guide to Utility Program Functions," which is a table arranged in alphabetical 
order of utility program functions and the programs that perform them. This table 
enables you to get to the program that can do what you need to have done. For 
additional information, see "Special Referencing Aids" below. 

• "Introduction," which introduces the utility programs and provides information on 
the differences among system, data set, and independent utility programs. This 
chapter contains basic information about how the programs are executed and about 
the utility control statements used to specify program functions. New or infrequent 
users of the utility programs should give particular attention to this chapter. 

• 22 individual chapters — one for each utility program. These chapters are in 
alphabetical order, beginning with IBCDASDI and ending with IFHSTATR. For a 
discussion of the organization of these chapters, which will help you find the 
information you need about a particular program, see "Organization of Program 
Descriptions" below. 

• "Appendix A: Exit Routine Linkage," which provides information about linking to 
and returning from optional user-supplied exit routines. You should read this 
appendix if you plan to code or use an exit routine. If you are coding an exit 
routine, this appendix provides linkage conventions, descriptions of parameter lists, 
and return codes. If you are using an existing exit routine, you may be interested in 
the meaning of return codes from the exit routine. 

• "Appendix B: Invoking Utility Programs from a Problem Program," which describes 
the macro instructions used to invoke a utility program from a problem program 
rather than executing the utility program by job control statements or by a 
procedure in the procedure library. You should read this appendix if you plan to 
invoke a utility program from a problem program. 

• "Appendix C: DD Statements for Defining Mountable Devices," which provides a 
review of how to define mountable volumes to ensure that no one else has access 
to them. For a definitive explanation of this subject, see OS Job Control Language 
Reference, GC28-6704. 

• "Appendix D: Generation Data Groups," which describes generation data groups 
and their indexes, and how to catalog and retrieve generation data sets. This 
appendix is included because generation data groups are not fully described 
elsewhere and because you need this background information if you are to 
manipulate generation data groups with the utility programs. You should read this 
appendix if you intend to use utility programs to create or manipulate generation 
data sets. 

• "Appendix E: Processing User Labels," which describes the user-label processing 
that can be performed by lEBGENER, lEBCOMPR, lEBPTPCH, lEHMOVE, lEBTCRIN, 
and lEBUPDTE. You should read this appendix if you plan to use a utility program 
for processing user labels. 
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Organization of 
Program Descriptions 



Special Referencing Aids 



• "Index," which is a subject index to this publication. 

Program descriptions are all organized the same way to enable you to find 
information more easily. Each program is discussed according to the following pattern: 

• Introduction to and description of the functions that can be performed by the 
program. This description typically includes an overview of the program's use, 
definitions of terms, illustrations, etc. 

• Input and output (including return codes) used and produced by the program. 

• Control of the program through job control statements and utility control 
statements. A brief explanation of the job control statements used to execute the 
program appears in a table under "Job Control Statements." Any restrictions on 
job control statements appear under a "Restrictions" heading. The utility control 
statements are introduced in a list under "Utility Control Statements" so that you 
can determine which of the statements are required for the task to be performed. 

• Examples of using the program, including the job control statements and utility 
control statements. 

Two special referencing aids are included in this publication to help you: 

1. Locate the right utility program. 

2. Locate the right example. 

To locate the right utility program, refer to Table 1 in "Guide to Utility Program 
Functions," which immediately precedes the "Introduction." Figure 1 shows a portion 
of the table. The figure shows that you can use lEHINITT to label a magnetic tape 
volume or lEHLIST to list a volume table of contents. 



Label magnetic tape volumes lEHINITT 

List a password entry lEHPROGM 

a volume table of contents lEHLIST 

partitioned directories lEHLIST 

Figure 1. Locating the Right Program 



To locate the right example, use the table — called an "example directory" — that 
precedes each program's examples. Figure 2 shows a portion of the example directory 
for lEHMOVE. The figure shows that lEHMOVE Example 1 is an example of moving a 
sequential data set and that lEHMOVE Example 2 is an example of copying a 
sequential data set. 



Required Publications 



MOVE Sequential 



COPY Sequential 



2301 Drum, 
2311 Disks 



2311 Disk, 
2301 Drum, 
2314 or 
2319 Disks 



Source volume is demounted 
after job completion. 
Two mountable disks. 

Three cataloged sequential 
data sets are to be copied. 
The 2314 or 2319 are 
mountable. 



Figure 2. Locating the Right Example 



The reader should be familiar with the following publications: 

• OS Messages & Codes, GC28-6631, which contains a complete listing and 
explanation of the messages and codes issued by the utility programs and other 
programs. 

• OS JCL Reference, GC28-6704, which contains a complete explanation of the job 
control statements available for the operating system. 

• OS Data Management Services Guide, GC26-3746, which describes the input/output 
facilities of the operating system. It contains information on record formats, data 
set organization, access methods, direct access device characteristics, data set 
disposition, and space allocation. 

• OS Supervisor Services Guide, GC28-6646, which contains information on how to 
use the services of the supervisor. Among the services of the supervisor are 
program management, task creation and management, main storage management, 
and checkpoint and restart. 

• OS Supervisor and Data Managen^ent Macro Instructions, GC28-6647, which 
contains a description of the WRITE SZ, LINK, and RETURN macro instructions, and 
contains the format and contents of the DCB. 
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Related Publications 



Notational Conventions 

Bold Type 
Italic Type 



Punctuation 



Brackets 



Braces 



Underscoring 



Ellipsis 



The additional publications referred to in this publication are: 

• OS Data Management for System Programmers, GC28-6550, which contains 
information on the PASSWORD data set and on writing optional user-supplied exit 
routines. 

• OS Storage Estimates, GC28-6551, which contains storage estimates. 

• OS System Control Blocks, GC28-6628, which contains a complete description of 
the control blocks used by the operating system. 

• IBM System/360 Principles of Operation, GA22-6821, which contains a description 
of system structure; of the arithmetic, logical, branching, status switching, and 
input/output operations; and of the interruption system. 

A uniform system of notation is used to describe the syntax (or format) of utility 
control statements. This notation provides a basis for describing the structure of utility 
control statements. That is, it describes which parameters are required and which are 
optional, the options available in expressing values, and the required punctuation. 

In the notation, bold type (LIST, 0, etc.) is used to indicate specific values that can be 
entered. 

Italic type (nn, user-information, etc.) is used where a number, character string, or 
keyword is to be inserted by the user. For instance, the italic letters in 

MODE = mm 
Tn 

must be replaced by a value when coded. 

The period, comma, equal sign, parentheses, and apostrophe are used for 
punctuation and must be coded as shown. These punctuation marks serve to separate 
the parameters of a utility control statement. 

Brackets ([ ]) indicate that the elements and punctuation they enclose are optional. 
The brackets themselves are for descriptive purposes only, and are not to be coded. 
For instance 

value = elementl,element2,element3[,element4] 

indicates that "value = " must be followed by three required parameters (elementl, 
element2, and elements) separated by commas. As indicated by the brackets, 
element4 is optional and need not be coded. If element4 is coded, however, the 
comma that immediately precedes it must also be coded. 

When choices are available for an optional value, the choices appear in brackets, one 
choice above another, as follows: 

value = elementO [.elementl ] 
[,element2] 
[.elements ] 

In the above example, "value = " must be followed by elementO. Optionally, 
elementl. element2. or elements can be coded. 

Braces ({ }) indicate a required choice. The braces themselves are for descriptive 
purposes only, and are not to be coded. For example: 

value = {elementl } 
{element2} 

indicates that "value = " must be followed by either elementl or element2. 

Underscoring indicates a value that is assumed by the program if no value is entered 
for that element. For example, given that no optional value is coded in the following: 

value = [ elementl 1 
[element2] 

elementl is assumed. 

Ellipsis (...) is used to indicate that one or more additional parameters or sets of 
parameters, each of the same format, optionally can be added to the operand. For 
example, given the following 

value = elementl, element2... 

the ellipsis indicates that everything preceding the ellipsis and following the equal sign 
can be repeated. 
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KEYWORD = device-list 



The term KEYWORD is replaced by either VOL, OVOL, FROIVI, or TO. 

The term deWce is replaced by either a generic name, e.g. 3330; or a substitute for a 
generic name, e.g. DISK, if this substitute has been generated into your system. 

For direct access devices, the term list is replaced by one or more volume serial 
numbers separated by commas. When there is more than one, the entire list field must 
be enclosed in parentheses. 

For tape, the term list is replaced by either one or more volume serial 
number-comma-data set sequence number pairs. Each pair is enclosed in braces and 
separated from the next pair by a comma. When there is more than one pair, the 
entire list field must be enclosed in parentheses. 
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Summary of Major Changes for Release 21.7 



Major Technical Changes 



Major Editorial Changes 



Following is a summary of major technical and editorial changes. 

There are no major technical changes. Minor maintenance corrections have been 
made where applicable. 

Following is a summary of the major editorial changes to this publication for Release 
21.7: 

• The examples have been modified, where necessary, to reflect proper placement of 
continuation for JCL and utility control statements. 

• Various examples throughout the publication have been modified to reflect usage of 
more recent device technologies. 

• Additional examples have been included for lEHATLAS, lEHDASDR, and lEHMOVE. 

Note: The following programs have been put into Class C Programming Maintenance 
classification as of December 15, 1972, and are marked "Class C" at the start of 
each of their descriptions in this publication. 

IBCRCVRP lEBISAM 

lEBCOMPR lEBPTPCH 

lEBGENER lEBUPDAT 
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Guide to Utility Program Functions 



Table 1 shows a list of tasks that the utility programs can be used to perform. The 
left-hand column shows tasks that you might want to perform. The middle column 
more specifically defines the tasks. The right-hand column shows the utility programs 
that can be used for each task. Notice that in some cases more than one program may 
be available to perform the same task. 



Table 1. Tasks and Utility Programs 

Operation 





Add 


a password 




1 


Analyze 


tracks on direct access 


1 




Assign alternate 
tracks 


to a direct access volume 


1 




Build 


a generation index 
a generation 
an index 






Catalog 


a data set 

a generation data set 






Change 


data set organization 
logical record length 
volume serial number of direct access 


volume 




Compare 


a partitioned data set 
sequential data sets 






Compress-in- 
place 


a partitioned data set 






Connect 


volumes 






Construct 


records from MTST and MIDI input 






Convert to 






1 


partitioned 
Convert to 


a sequential data set created as a 
result of an unload 
sequential data sets 






sequential 


a partitioned data set 





Copy 



Create 



Delete 



Dump 



an indexed sequential data set 

a catalog 

a direct access volume 

a partitioned data set 

a volume of data sets 

an indexed sequential data set 

cataloged data sets 

dumped data from tape to direct access 

job steps 

members 

selected members 

sequential data sets 

to tape 

a library of partitioned members 

a member 

a sequential output data set 

an index 

an output job stream 

a password 

an index structure 

records from a member 

records in a partitioned data set 

a direct access volume 



Utility 

lEHPROGM 
lEHATLAS, lEHDASDR, IBCDASDI 

lEHDASDR, IBCDASDI, lEHATLAS 

lEHPROGM 
lEHPROGM 
lEHPROGM 

lEHPROGM 
lEHPROGM 

lEBUPDTE 
lEBGENER 
lEHDASDR 

lEBCOMPR 
lEBCOMPR 

lEBCOPY 

lEHPROGM 

lEBTCRIN 



lEBCOPY 
lEBUPDTE, lEBGENER 

lEBUPDTE 
lEBISAM, lEBDG 

lEHMOVE 

lEHDASDR, lEHMOVE, IBCDMPRS 

lEBCOPY, lEHMOVE 

lEHMOVE 

lEBISAM 

lEHMOVE 

lEHDASDR, IBCDMPRS 

lEBEDIT 

lEBUPDAT, lEBGENER, lEBUPDTE, lEBDG 

lEBCOPY, lEHMOVE 

lEBGENER, lEHMOVE, lEBUPDTE 

IBCDMPRS 

lEBUPDTE 

lEBDG 

lEBDG 

lEHPROGM 

lEBEDIT 

lEHPROGM 
lEHPROGM 
lEBUPDAT 
lEBUPDTE 

lEHDASDR, IBCDMPRS 
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Operation 




Utility 


Edit 


MTDI input 


lEBTCRIN 


Edit and convert 
to partitioned 


a sequential data set 


lEBGENER, lEBUPDTE 


Edit and copy 


a job stream 

a sequential data set 


lEBEDIT 
lEBGENER, lEBUPDTE 


Edit and list 


error statistics by volume (ESV) records 


IFHSTATR 


Edit and print 


a sequential data set 


lEBPTPCH 


Edit and punch 


a sequential data set 


lEBPTPCH 


Enter 


a procedure into a procedure library 


lEBUPDTE 


Exclude 


a partitioned data set member from a copy operation 


lEBCOPY, lEHMOVE 


Expand 


a partitioned data set 
a sequential data set 


lEBCOPY 
lEBGENER 


Generate 


test data 


lEBDG 


Get alternate 
tracks 


on a direct access volume lEHDASDR 


!, IBCDASDI, lEHATLAS 


Include 


changes to members or sequential data sets 
source language modifications in a symbolic library 


lEBUPDTE 
lEBUPDAT 


Initialize 


a direct access volume 
a tape 


lEHDASDR, IBCDASDI 
lEHINITT 


Insert records 


into a partitioned data set 


lEBUPDTE 


Label 


magnetic tape volumes 


lEHINITT 


List 


a password entry 
a volume table of contents 
contents of direct access volume on system output 
device 

number of unused directory blocks and tracks 
partitioned directories 
the contents of the catalog (SYSCTLG 
data set) 


lEHPROGM 
lEHLIST 

lEHDASDR 

lEBCOPY 

lEHLIST 

lEHLIST 


Load 


a previously unloaded partitioned data set 

an indexed sequential data set 

an unloaded data set 

UCS and FCB buffers of a 321 1 


lEBCOPY 

lEBISAM 

lEHMOVE 

ICAPRTBL 


Merge 


partitioned data sets 


lEHMOVE, lEBCOPY 


Modify 


a partitioned or sequential data set 


lEBUPDTE 


Move 


a catalog 

a volume of data sets 
cataloged data sets 
partitioned data sets 
sequential data sets 


lEHMOVE 
lEHMOVE 
lEHMOVE 
lEHMOVE 
lEHMOVE 


Number records 


in a new member 

in a partitioned data set 


lEBUPDAT, lEBUPDTE 
lEBUPDTE 


Password protect 


add a password 
delete a password 
list passwords 
replace a password 


lEHPROGM 
lEHPROGM 
lEHPROGM 
lEHPROGM 



Print 

Punch 

Read 
Reblock 

Recover 

Release 
Rename 



a sequential data set 
partitioned data sets 
selected records 

a partitioned data set member 
a sequential data set 
selected records 

Tape Cartridge Reader input 

a partitioned data set 
a sequential data set 

data from defective tracks on direct access 
volumes 

a connected volume 

a partitioned data set member 
a sequential or partitioned data set 
moved or copied members 



lEBGENER, lEBUPDTE, lEBPTPCH 
lEBPTPCH 
lEBPTPCH 

lEBPTPCH 
lEBPTPCH 
lEBPTPCH 

lEBTCRIN 

lEBCOPY 
lEBGENER, lEBUPDTE 

IBCRCVRP, lEHATLAS 

lEHPROGM 

lEBCOPY, lEHPROGM 

lEHPROGM 

lEHMOVE 
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Operation 




Utility 


Renumber 


logical records 


lEBUPDTE, lEBUPDAT 


Replace 


a password 


lEHPROGM 




bad data on a defective track 


IBCRCVRP 




data on an alternate track 


IBCRCVRP, lEHATLAS 




identically named members 


lEBCOPY 




logical records 


lEBUPDTE 




members 


lEBUPDAT, lEBUPDTE 




records in a member 


lEBUPDAT, lEBUPDTE 




records in a partitioned data set 


lEBUPDTE, lEBCOPY 




selected members 


lEBCOPY 




selected members in a move or copy operation 


lEHMOVE, lEBCOPY 


Restore 


a dumped direct access volume from tape 


IBCDMPRS, lEHDASDR 


Retrieve 


usable data from a defective track 


IBCRCVRP 


Scratch 


a volume table of contents 


lEHPROGM 




data sets 


lEHPROGM 


Uncatalog 


data sets 


lEHPROGM 


Unload 


a partitioned data set 


lEBCOPY, lEHMOVE 




a sequential data set 


lEHMOVE 




an indexed sequential data set 


lEBISAM 


Update 


in place a partitioned data set 


lEBUPDTE 




TTR entries in the supervisor call library 


lEHIOSUP 


Write 


IPL records and a program on a direct 


IBCDASI, 




access volume 


lEHDASDR 
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Introduction 



Control 



Job Control Statements 



Utility Control Statements 



The IBM System/360 Operating System provides utility programs to assist in 
organizing and maintaining data. Each utility program described in this publication falls 
into one of three classes of programs. The program class into which a utility program 
falls is determined by the function that the utility program performs and the manner in 
which the program is controlled. The program classes are: 

• System utility programs, which are used to maintain system control data at an 
organizational or system level. These programs are controlled by job control 
statements and utility control statements. 

• Data set utility programs, which are used to reorganize, change, or compare data at 
the data set and/or record level. These programs are controlled by job control 
statements and utility control statements. 

• Independent utility programs, which are used to prepare devices for system use 
when the operating system is not available. Independent utility programs operate 
outside, and in support of, IBM System/360 Operating System. These programs 
are controlled by utility control statements. 

The selection of a specific program is dependent on the nature of the job to be 
performed. For example, renaming a data set involves modifying system control data. 
Therefore, a system utility program can be used to rename the data set. In some 
cases, a specific function can be performed by more than one program. Table 1 in 
"Guide to Utility Program Functions," which immediately precedes this chapter, is 
provided to help you find the program that performs the function you need. 

System and data set utility programs are controlled by job control statements and 
utility control statements. Independent utility programs are controlled by utility control 
statements; because these programs are independent of the operating system, job 
control statements are not required. The job control statements and utility control 
statements necessary to use utility programs are provided in the major discussion of 
each utility program. 

A system or data set utility program can be introduced to the operating system in 
different ways: 

• Job control statements can be included in the input stream. 

• Job control statements, placed in a procedure library or defined as an inline 
procedure, can be included by means of the EXEC job control statement. 

• A utility program can be invoked by a calling program. 

If job control statements are placed in a procedure library, they should satisfy the 
requirements for most applications of the program; a procedure, of course, can be 
modified or supplemented for applications that require additional parameters, data 
sets, or devices. The data set utility lEBUPDTE can be used to enter a procedure into 
a procedure library; see "lEBUPDTE Program." 

Independent utility programs do not require job control statements and cannot be 
invoked by a calling program. For information on executing independent utility 
programs, see "Independent Utility Programs" below. 

Utility control statements are used to identify a particular function to be performed by 
a utility program and, when required, to identify specific volumes or data sets to be 
processed. 

The control statements for the IBM System/360 Operating System utility programs 
have the following standard format: 

label operation operand comments •■ 

The label symbolically identifies the control statement and, with the exception of 
system utility program lEHINITT, can be omitted. When included, a name must begin in 
the first position of the statement and must be followed by one or more blanks. It can 
contain from one to eight alphameric characters, the first of which must be alphabetic. 

The operation identifies the type of control statement. It must be preceded and 
followed by one or more blanks. 

The operand is made up of one or more keyword parameters separated by commas. 
The operand field must be preceded and followed by one or more blanks. Commas, 
parentheses, and blanks can be used only as delimiting characters. 



Introduction 23 



Continuing Utility 
Control Statements 



Restrictions 



Multiprogramming 
Considerations 



System Utility Programs 



Comments can be written in a utility statement, but they must be separated from the 
last parameter of the operand field by one or more blanks. 

Utility control statements are coded on cards or as card images and are contained in 
columns 1 through 71. A statement that exceeds 71 characters can be continued on 
one or more additional cards. The label and operation fields must appear on the first 
card. The operand, however, can be interrupted after any comma; a comment can be 
interrupted after any column. Comments can be placed on any card containing a 
complete or partial operand. However, when a comment is placed on a card with a 
partial operand, the comment cannot be continued. A nonblank character must be 
placed in column 72 to indicate continuation. 

The continued portion of the utility control statement must begin in 
column 16 of the following statement. (Job control language continuations can begin 
in any column from 4 through 16, and do not require a nonblank character in column 
72 for continued operand fields.) Comments can be placed on any card containing a 
complete or partial statement. However, when a card is included for the sole purpose 
of continuing a comment, the continuation must begin in column 16. 

Note: The lEBCOPY, IBCRCVRP, lEBPTPCH, lEBGENER, lEBCOMPR, and lEBDG utility 
programs permit certain exceptions to these requirements (see the applicable 
program description). 

The utility control statements are discussed in detail, as applicable, in the remaining 
chapters. 

• A substitute name that represents two or more different device types (for example, 
DISK, meaning 2311 and 2314) cannot be processed by a utility program. 

• Unless otherwise indicated in the description of a specific utility program, a 
temporary data set can be processed by a utility program only if the user specifies 
the complete name generated for the data set by the system (for example, 
DSNAME = SYS68296.T000051.RP001.JOBTEMP.TEMPMOD). 

In an MVT environment, a region size should be specified for each application of a 
system or data set utility program. The region size is determined by the number of 
bytes in the utility program and by the block sizes of the data sets used in the job 
step). A region size can be specified as a parameter in the EXEC statement specifying 
the utility program name. Refer to "Job Control Statements" under each utility 
program for the minimum region size. 

A job that modifies a system data set (identified by SYSl.) must be run in a single job 
environment; however, a job that uses a system data set, but does not modify it, can 
be run in a multiprogramming environment. The operator should be informed of all 
jobs that modify system data sets. 

DD statements should ensure that the volumes on which the data sets reside cannot 
be shared when update activity is being performed. 

System utility programs manipulate collections of data and system control information. 
The system utility programs are: 

lEHATLAS, which is used to assign alternate tracks when defective tracks are 
indicated. 

lEHDASDR, which is used to initialize direct access volumes or to dump or restore 
data. 

lEHINITT, which is used to write standard labels on tape volumes. 

lEHIOSUP, which is used to update entries in the supervisor call library. 

lEHLIST, which is used to list system control data. 

lEHMOVE, which is used to move or copy collections of data. 

lEHPROGM, which is used to build and maintain system control data. 

IFHSTATR, which is used to select, format, and write information about tape errors 
from the IFASMFDP tape or the SYSl. MAN data set. 

A system utility program is executed or invoked through the use of job control 
statements and utility control statements. 

System utility programs can be executed as jobs or can be invoked as subroutines by 
a calling program. The invocation of utility programs and the linkage conventions are 
discussed in "Appendix B: Invoking Utility Programs from a Problem Program." 
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Data Set Utility Programs 



Independent Utility 
Programs 



When using system utility programs, be sure that: 

• Each data set to be used by programs other than lEHPROGM, lEHMOVE, and 
lEHLIST is defined on a DD statement specifying the data set name and 

DISP = OLD. When updating activity is being performed by lEHPROGM, lEHMOVE, 
lEHLIST, or lEHDASDR in a multiprogramming environment, other tasks should not 
be allowed to access the data set being updated. (Refer to "Appendix C: DD 
Statements for Defining Mountable Devices" for precautions to Jse taken.) 

• DD statements defining mountable devices specify that volumes mounted on those 
devices cannot be shared. 

• Mountable volumes are not made available to the system until the user is requested 
by the system to mount the specified volumes. 

• A reader procedure is used that will direct input and output data sets to volumes 
other than those which are to be modified by a system utility program. 

• When executing a SCRATCH operation, the data set or volume being scratched is 
not being used by a program executing concurrently. 

Data set utility programs manipulate partitioned, sequential, or indexed sequential 
data sets provided as input to the programs. Data ranging from fields within a logical 
record to entire data sets can be manipulated. The data set utility programs are: 

lEBCOMPR, which is used to compare records in sequential or partitioned data 
sets. 

lEBCOPY, which is used to copy, compress, or merge partitioned data sets, to 
select or exclude specified members in a copy operation, and to rename and/or 
replace selected members of partitioned data sets. 

lEBDG, which is used to create a test data set consisting of patterned data. 

lEBEDIT, which is used to selectively copy job steps and their associated JOB 
statements. 

lEBGENER, which is used to copy records from a sequential data set or to convert a 
data set from sequential organization to partitioned organization. 

lEBISAM, which is used to place source data from an indexed sequential data set 
into a sequential data set in a format suitable for subsequent reconstruction. 

lEBPTPCH, which is used to print or punch records that reside in a sequential or 
partitioned data set. 

lEBTCRIN, which is used to construct records from the input data stream that have 
been read from the IBM 2495 Tape Cartridge Reader. 

lEBUPDAT, which is used to incorporate changes to symbolic libraries. 

lEBUPDTE, which is used to incorporate changes to sequential or partitioned data 
sets. 

Data set utility programs can be executed as jobs or can be invoked as subroutines by 
a calling program. The invocation of utility programs and the linkage conventions are 
discussed in "Appendix B: Invoking Utility Programs from a Problem Program." 

Independent utility programs operate outside, and in support of, the IBM System/360 
Operating System. They are not supported, however, by the 3066 console, which is 
only used with the Model 165, System/370. If the 3066 is the only console available, 
execute independent utilities by following step 3b "Executing IBCDASDI, IBCDMPRS, 
IBCRCVRP" below. The independent utility programs are: 

• IBCDASDI, which is used to initialize a direct access volume and to assign alternate 
tracks. 

• IBCDMPRS, which is used to dump and restore the data contents of a direct access 
volume. 

• IBCRCVRP, which is used to recover usable data from a defective track, assign an 
alternate track, and merge replacement data with the recovered data onto the 
alternate track. 

• ICAPRTBL, which is used to load the forms control and Universal Character Set 
buffers of a 3211 after an unsuccessful attempt to IPL with the 3211 printer 
assigned as the output portion of a composite console. 
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Executing IBCDASDI, 
IBCDMPRS, and IBCRCVRP 



Executing ICAPRTBL 



IBCDASDI, IBCDMPRS, and IBCRCVRP are loaded as card decks or as card images on 
tape. Control statements for the requested program can follow the last card or card 
image of the program, or can be entered on a separate input device. To execute 
IBCDASDI, IBCDMPRS, or IBCRCVRP: 

1. Place the object program deck in the reader or mount the tape reel that contains 
the object program. 

2. Load the object program from the reader or tape drive by setting the load selector 
switches and pressing the console LOAD key. When the program is loaded, the wait 
state is entered and the console lights display the hexadecimal value FFFF. 

3. Define the control statement input device in one of the following ways: 

(a) Press the REQUEST key of the console typewriter and, in response to the 
message "DEFINE INPUT DEVICE", enter "INPUT = xxxx,cuu". The xxxx is the 
device type, c is the channel address, and uu is the unit address. The device 
type can be 1402, 1442, 2400, 2501, or 2540. 

(b) If the console typewriter is not available, enter at storage location 0110 
(hexadecimal): Icuu for a 1442 Card Read Punch; 2cuu for a 2400 9-track 
tape drive; or Ocuu for a 2540 Card Read Punch, 2501 card reader, 3410 tape, 
or 3420 tape. Press the console INTERRUPT key. 

4. Control statements are printed on the message output device. At the end of the 
job, "END OF JOB" is printed on the message output device and the program 
enters the wait state. 

If the job executes IBCRCVRP and the message output device is a tape, the console 
lights display the hexadecimal value DDDD at a normal end of the job and EEEE at an 
abnormal end of job. If a machine check occurs, 00E2 is displayed. 

ICAPRTBL must be loaded from a card reader. Control statements must follow the last 
card of the program. Only one printer can be initialized each time the program is 
executed. 

To execute ICAPRTBL: 

1. Mount the correct train on the printer and ready the printer. 

2. Place the object program deck and the control cards in the card reader. Ready the 
reader and press the end-of-file key. 

3. Load the object program from the reader by setting the load selector switches and 
pressing the console LOAD key. 

Wait state codes will be displayed in the address portion of the PSW for normal 
termination and for input/output, system or control card errors. Code BOl is issued 
for normal termination; B02 through B07 are issued for control card errors; BOA 
through BOC are issued for system errors; and Bll through BID are issued for 
input/output errors. Table 2 shows these codes and their meanings. For a detailed 
discussion of the wait-state codes, see OS Messages & Codes, GC28-6631. 



Table 2. ICAPRTBL Wait-State Codes 



Code 


Meaning 


Cod 


BOl 


Visually check the train image 


812 




printed on the 3211. 


B13 


B02 


Missing control card or control 
card out ot order. 




803 


Incorrect JOB statement. 


814 


804 


Incorrect DFN statement. 


815 


805 


Incorrect UCS statement. 


819 


806 


Incorrect FCB statement. 


81A 


807 


Incorrect END statement. 


818 


80A 


External interrupt. 




808 


Program check interrupt. 




BOC 


Machine check interrupt. 


BIC 


811 


Reader not online. 


BID 



Code Meaning 



Reader not ready. 

Reader unit check (display low 

main storage location 3 for 

sense information). 

Reader channel error. 

No device end on reader. 

Printer not online. 

Printer not ready. 

Printer unit check (display low 

main storage location 2 

through 7 for sense information). 

Printer channel error. 

No device end on printer. 
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IBCDASDI is an independent utility used to initialize direct access volumes for use and 
to assign alternate tracks on nondrum, direct access storage volumes. (See 
"Introduction" for general independent utility information.) IBCDASDI jobs can be 
performed continuously by stacking complete sets of control statements. 

IBCDASDI is not supported on MP65 with the mode switch set to MS; the mode switch 
must be set to 65. 

IBCDASDI can be used to initialize a direct access volume. A volume can be initialized 
with or without surface analysis, a test for defective tracks; however, a surface 
analysis should be performed when a volume is initialized for the first time. 

Note: A 2321 volume is automatically initialized with a surface analysis. 

When a volume is initialized, IBCDASDI: 

• Checks for tracks that have been previously designated as defective (flagged) and 
have had alternates assigned. This test must be suppressed when a disk is 
initialized with surface analysis for the first time. This test must not be suppressed 
when a volume is initialized without surface analysis. 

• Automatically assigns alternates, if necessary, when a volume is initialized with 
surface analysis. Tracks that are available for disposition as alternates are checked 
first. 

• Writes a track descriptor record (record 0) and erases the remainder of each track. 
When a volume is initialized with surface analysis, IBCDASDI also writes a standard 
home address. 

• Writes IPL records on track (records 1 and 2). 

• Writes volume label on track (record 3) and provides space for additional 
records, if requested. 

• Constructs and writes a volume table of contents (VTOC). 

• Writes an IPL program, if requested. When a volume is initialized with surface 
analysis, the IPL program is written on track for 2301, 2305, 2314, or 2319 
volumes or track 1 for 2303 or 2311 volumes. When a volume is initialized without 
surface analysis, the IPL program is written on track for 2301, 2305, 2314, 
2319, or 3330 volumes or on track 1 for 2303 or 2311 volumes. 

Note: Defective tracks are flagged and alternate tracks are assigned when the 3330 
storage volumes are initialized at the factory. An IBCDASDI job to initialize a 3330 will 
not perform a surface analysis. The quick DASDI, which can be performed on a 3330 
volume, includes: (1) reading alternate tracks and decreasing the total count of the 
alternates by one when an alternate is found defective or assigned; (2) writing a 
volume label and VTOC; and (3) writing IPLTXT, if requested. Note that surface 
analysis is not performed and neither the home address nor record is written on the 
primary tracks. The BYPASS and FLAGTEST options of the DADEF statement are 
ignored. (See "DADEF Statement" below.) 

IBCDASDI can be used to: (1) test a track and, if necessary, assign an alternate or 
(2) bypass testing and automatically assign an alternate. 

If testing is performed, an alternate track is assigned for any track found defective. If 
the defective track is an unassigned alternate, it is flagged to prevent its future use. 
The alternate track address is made known to the operator. 

If a track is tested and not found to be defective, no alternate is assigned. The 
operator is notified by a message. 

If testing is bypassed, an alternate track can be assigned for the specified track or its 
alternate, whether it is defective or not. If the specified track is an unassigned 
alternate, it is flagged to prevent its future use. 

IBCDASDI uses as input a control data set, which consists of utility control statements. 

IBCDASDI produces as output an initialized direct access volume and a message data 
set. 

IBCDASDI is controlled by utility control statements. Because IBCDASDI is an 
independent utility, operating system job control statements are not used. 

IBCDASDI utility control statements in the order in which they must appear are: 

• JOB statement, which is used to indicate the beginning of an IBCDASDI job. 
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DADEF Statement 



• MSG statement, which is used to define an output device for operator messages. 

• DADEF statement, which is used to define the volume to be initialized. 

• VLD statement, which contains information for constructing an Initial volume label 
and for allocating space for additional labels. 

• VTOCD statement, which contains information for controlling the location of the 
volume table of contents. 

• IPLTXT statement, which is used to separate utility control statements from any IPL 
program text statements. 

• GETALT statement, which Is used to assign an alternate track on a volume. 

• END statement, which is used to indicate the end of an IBCDASDI job. 

• LASTCARD statement, which is used to end a series of stacked IBCDASDI jobs. 

Note: An IBCDASDI job that initializes a 2321 Data Cell cannot follow one that 
initializes a different device type unless IBCDASDI is reloaded. 

The JOB statement indicates the beginning of an IBCDASDI job. 

The format of the JOB statement is: 

[label] JOB [user-/nformat/on] 

JOB must be preceded and followed by at least one blank. 

The MSG statement defines an output device for operator messages. It follows the 
JOB statement and precedes any function definition statements. 

The format of the MSG statement is: 

[label] MSG TODEV = xxxx 



.TODADDR = cuu 



where: 



TODEV = xxxx 

specifies the type of output device to receive messages, for example, 1403. The 
devices that can be specified are 1403, 1443, 1052, 2400, 3210, and 3211. 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the message output 
device. 

The DADEF statement defines the direct access volume to be initialized. 

The format of the DADEF statement is: 

; [label] DADEF TODEV = xxxx 

.TOADDR = cuu 

[,IPL = YES] 

,VOLID= {serial } 
{SCRATCH} 

[.FLAGTEST = NO] 

[.PASSES = n] 

[.BYPASS = YES] 

[.BIN = d] 

[.MODEL = n] 
where: 

TODEV = xxxx 

specifies the type of the direct access device to be initialized, for example, 2314. 
Note that the 2319 disk is functionally equivalent to the 2314 disk. To use a 2319, 
specify 2314 in the TODEV parameter. 

TOADDR = cuu 

specifies channel number, c, and unit number, uu, of the device. 

IPL = YES 

specifies that an IPL program is to be written on the volume. An IPL initialization 
program must be written on a device to be used for system residence. If IPL is 
omitted, no IPL program is written. 
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VOLID = 

specifies whether a volume serial number check is to be made. These values can be 
coded: 

serial 

specifies the volume serial number of the volume to be initialized. If serial does 
not match the volume serial number found on the volume to be initialized, the 
operator is notified and the job is terminated. 

SCRATCH 

specifies that no volume serial number check is to be made. 

FLAGTEST=NO 

specifies that no check is to be made for previously flagged tracks on a disk 
volume before surface analysis is performed. FLAGTEST = NO should be specified 
when the disk recording surface is initialized for the first time. Because no check is 
made for previously flagged tracks on drum volumes or on 2321 volumes, 
FLAGTEST = NO need not be coded when these devices are initialized. 

PASSES = n 

specifies the number of passes per track to be made in checking for defective 
tracks. PASSES is valid when surface analysis is to be performed or when a quick 
DASDI is to be performed on a 3330 volume. The value n can be through 255. 
The specification indicates that a quick DASDI is to be performed on a 3330 
volume. For a 3330 volume, a value greater than causes no check to be made for 
defective tracks. A specification of 1 through 255 indicates the number of passes 
to be made per track for volumes other than a 3330 volume. If PASSES is omitted, 
one pass is made per track. This parameter does not apply to 2321 volumes. 

BYPASS = YES 

specifies that no check is to be made for defective tracks. If BYPASS is omitted, 
tracks are checked and those found defective are automatically assigned 
alternates. This parameter applies only when surface analysis is not to be 
performed; it does not apply to 2321 volumes. 

BIN = c/ 

specifies the decimal number of a bin to be initialized. The value of d can be 
through 9. This parameter applies only to 2321 volumes. 

MODEL = n 

specifies a decimal model number (1 or 2). This parameter corresponds to the 
2305-1 and 2305-2, respectively. MODEL is required when a 2305 is to be 
initialized. 

VLD Statement The VLD statement contains information for constructing an initial volume label and 

for allocating space for additional labels. 

The format of the VLD statement is: 

! [/abeOVLD NEWVOLID = sena/ ] 

! [,VOLPASS = (0 } 

{T}] • •! 

[,OWNERID = xxxxxxxxxx] j 

i____^ [jADDLABEL^nL^^ ^ __,_„^__ __,_____,_, _,_,_^ ..^...,_J 

where: 

NEWVOLID = serial 

specifies a one- to six-character volume serial number. 

VOLPASS = 

specifies the value of the volume security bit. These values can be coded: 



specifies that the volume is not security protected. If VOLPASS is omitted, is 
assumed. 

1 

specifies that the volume is security protected. 

OWNERID = xxxxxxxxxx 

specifies a one- to ten-character field that identifies the owner of the volume. If 
OWNERID is omitted, no identification is given. 

ADDLABEL = n 

specifies the total number of additional labels for which space is to be allocated. 
The value of n can be 1 through 7. If ADDLABEL is omitted, is assumed. 
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yjOCD statement 



The VTOCD statement contains information for controlling the location of the volume 
table of contents. 

The format of the VTOCD statement Is: ^^^ 

I [tebel] VTOCD STRTADR = nnnnn i 

L i,EXTCNT = nnnn „__ „ ^ „ _- 

where: 

STRTADR = nnnnn 

specifies the one- to five-byte track address, relative to the beginning of the 
volume, at which the volume table of contents is to begin. The VTOC cannot occupy 
track or any alternate track. 

EXTENT = nnnn 

specifies the length (number of tracks) of the VTOC. 

Table 3 shows the number of VTOC entries per track for each device type. 



IPLTXT Statement 



GET ALT Statement 



Table 3. VTOC Entries per Track 
Device VTOC Entries per Track 



2301 


63 


2314 


25 


2319 


25 


2302 


22 


2303 


17 


2311 


16 


2321 


8 


2305-1 


18 


2305-2 


34 


3330 


39 



The IPLTXT statement separates utility control statements from IPL program text 
statements. It is required only when IPL text is included. 

The format of the IPLTXT statement is: 

IPLTXT 

When IPL text is included, END must start in column 2. See "END Statement" below. 

The GETALT statement is used to assign an alternate track on a volume. Any number 
of alternate tracks can be assigned in a single job by including a GETALT statement 
for each track. 

Note: A GETALT statement that applies to a 3330 device causes an alternate track to 
be assigned automatically without testing. 

The format of the GETALT statement is: 

[/abe/] GETALT TODEV = xxxx 
,TOADDR = cuu 
.TRACK = cccchhhh 
.VOLID = serial 
[.FLAGTEST = NO] 
[.PASSES = n] 
[.BYPASS = YES] 
[,BIN = d] 
[.MODEL = n] 



where: 

TODEV = xxxx 

specifies the device type of the direct access device. 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the direct access device. 

TRACK = cccchhhh 

specifies the address of the track for which an alternate is requested, where cccc is 
the cylinder number and hhhh is the head number. 

VOLID = serial 

specifies the volume serial number of the volume to which an alternate track is to 
be assigned. If serial does not match the volume serial number found on this 
volume, the operator is notified and the job is terminated. 
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END Statement 



LASTCARD Statement 
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FLAGTEST = NO 

specifies that no check is to be made for a previously flagged track before a 
surface analysis for a disk volume is performed on this track. This parameter is 
used when testing before assigning an alternate. 

PASSES = n 

specifies the number of passes, n, to be made when performing a surface analysis 
on this track. The value of n can be 1 through 255. If PASSES is omitted, one pass 
is made. (If, however, the GETALT statement applies to a 3330 volume, an 
alternate track is assigned without testing; the PASSES parameter is ignored.) This 
parameter is used when testing before assigning an alternate. 

BYPASS = YES 

specifies that no check for a defective track is to be made. If BYPASS is omitted, 
the program assigns an alternate only if it finds that the specified track is defective. 

BiN = d 

specifies the decimal number of a bin to be initialized. The value of d can be 
through 9. This parameter applies only to 2321 volumes. 

MODEL = n 

specifies a decimal model number (1 or 2). This parameter corresponds to the 
2305-1 and 2305-2, respectively. MODEL is required when a 2305 is to be 
initialized. 

The GETALT function should not be used immediately after a RESTORE operation that 
did not complete successfully. Before using GETALT in such a case, reinitialize the 
volume, if possible. 

The END Statement denotes the end of job. It appears after the last function definition 
statement. 

The format of the END statement is: 

[label] END [user-information] 

END must be preceded and followed by at least one blank. When IPL text is included, 
END must start in column 2. 

The LASTCARD statement is required only when an IBCDASDI job or a series of 
stacked IBCDASDI jobs is followed by other statements on the control statement input 
device. The LASTCARD statement must follow the last END statement applying to an 
IBCDASDI job. 

The format of the LASTCARD statement is: 

LASTCARD 

The examples that follow illustrate some of the uses of IBCDASDI. Table 4 can be 
used as a quick reference guide to IBCDASDI examples. The numbers in the 
"Example" column point to examples that follow. 



Table 4. IBCDASDI Example Directory 



IBCDASDI Example 1 



Operation 

Initialize 
Initialize 
Initialize 



Assign alternate 
tracks 



Comments 

A 2305 volume is to be initialized with surface analysis. 

A 2305 volume is to be initialized without surface analysis. 

A 3330 volume to be used as the system residence volume 
is to be initialized. An IPL program is included in TXT format. 

Three alternate tracks are to be assigned on a 3330 volume. 



Example 
1 
2 

3 

4 



In this example, a 2305 volume is initialized for the first time. A surface analysis is 
performed with the initialization. 

The example follows: 

INIT JOB 'INITIALIZE 2305' 

MSG TODEV=1403,TOADDR=00E 
DADEF TODEV=2305 , TOADDR= 1 40 , VOLID=SCRATCH , FLAGTEST=NO 

VLD NEWV0LID=1 11111 
VTOCD S TRTADR= 5 , EXTENT^ 1 

END 

The control statements are discussed below: 

• JOB initiates the IBCDASDI job. 

• MSG defines the 1403 on channel 0, unit OE, as the output message device. 



IBCDASDI Program 31 



IBCDASDI Example 2 



IBCDASDI Example 3 



IBCDASDI Example 4 



• DADEF specifies that a 2305 volume on channel 1, unit 40, is to be initialized. 
Because the volume is being initialized for the first time, no check is to be made for 
previously flagged tracks. 

• VLD specifies 111111 as the volume serial number of the volume to be initialized. 

• VTOCD specifies the starting address and length in tracks of the volume table of 
contents. 

In this example, a 2305 volume is initialized for the first time. No surface analysis is 
performed with the initialization. 

The example follows: 

INIT JOB INITIALIZE 2305 

MSG TODEV=1403,TOADDR=00E 
DADEF TODEV=2305,TOADDR=140,VOLID=SCRATCH,BYPASS=YES 

VLD NEWVOLID=230500 
VTOCD STRTADR=1 ,EXTENT=3 

END 

The control statements are discussed below: 

• DADEF specifies that a 2305 volume is to be initialized and specifies the channel 
and unit number. No check is to be made for the volume serial number or for 
defective tracks. 

• VLD specifies the volume serial number of the volume to be initialized. 

• VTOCD specifies that the volume table of contents is to begin on track 1 and is to 
extend over three tracks. 

• END specifies the end of the IBCDASDI job. 

In this example, a 3330 volume is initialized for later use as a system residence 
volume. An IPL program is included in standard TXT format. 

The example follows: 

INIT JOB 'INITIALIZE 3330' 

MSG TODEV=1403,TOADDR=00E 

DADEF TODEV=3330 , T0ADDR=1 50 , IPL=YES 

VLD NEWVOLID=P00001 , OWNERID-BROWN , ADDLABEL=2 

VTOCD STRTADR=2 , EXTENT=9 
IPLTXT 
(IPL program text statements) 
END 

The control statements are discussed below: 

• DADEF specifies that a 3330 volume is to be initialized and specifies the channel 
number and unit number. An IPL program is to be included. 

• VLD specifies a volume serial number and owner identification for the volume to be 
initialized. It also specifies that space is to be allocated for two additional labels. 

• VTOCD specifies that the volume table of contents is to begin on track 2 and is to 
extend over nine tracks. 

• IPLTEXT specifies the beginning of IPL program text statements. 

• END specifies the end of IPL program text statements. Because IPL text is included, 
END begins in column 2. 

In this example, three alternate tracks are assigned to a 3330 volume, without 
reinitialization of the volume. The check for a defective track is bypassed when the 
first two of the three tracks are assigned. 

The example follows: 

ALTRK 



JOB ASSIGN ALTERNATE TRACKS ON 3330 
MSG TODEV=1052,TOADDR=009 
STMT1 GETALT TODEV=3330 ,T0ADDR=1 50 , VOLID=P00002 , 

BYPASS=YES , TRACK=006F000 1 
STMT2 GETALT TODEV=3330 , T0ADDR=1 50 , VOLID=P00002 , 

BYPASS=YES , TRACK=009 1 0004 
STMT 3 GETALT TODEV=3330 , T0ADDR=1 50 , 

TRACK=004B0007 , VOLID=P00002 
END 



lie 
lie 



The control statements are discussed below: 

• The first and second GETALT statements bypass the check for defective tracks. 

• The third GETALT statement causes the check for a defective track to be made 
because BYPASS is not included. 
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Control 
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JOB Statement 



MSG Statement 



DUMP Statement 



IBCDMPRS is an independent utility used to dump and restore data on direct access 
volumes. (See "Introduction" for general independent utility information.) 

The data contents of a direct access volume (all data except the home address) can 
be dumped to 2311, 2314, 2319, 2305, 3330, or tape volumes and restored to a 
direct access volume that resides on the same type of device as the source volume. 
Both the source volume and the volume to which data is to be restored must have 
been initialized to IBM System/360 Operating System specifications. IBCDMPRS is 
useful for preparing transportable copies and backup copies of direct access volumes. 

IBCDMPRS is not supported on MP65 with the mode switch set to MS; the mode 
switch must be set to 65. 

IBCDMPRS uses as input: 

• A control data set, which contains utility control statements. 

• A data set to be dumped to tape or to be restored to a direct access volume. 
IBCDMPRS produces as output: 

• A data set dumped to tape or a data set restored to a direct access volume. 

• A message data set. 

IBCDMPRS is controlled by utility control statements. Because IBCDMPRS is an 
independent utility, operating system job control statements are not used. 

IBCDMPRS utility control statements are: 

• JOB statement, which is used to begin an IBCDMPRS job. 

• MSG statement, which is used to define an output device for operator messages. 

• DUMP statement, which is used to identify the volume to be dumped and the 
receiving volume. 

• VDRL Statement, which is used to specify the upper and lower track limits of a 
partial dump. 

• RESTORE statement, which is used to identify the source volume whose data is to 
be restored and the receiving volume. 

• END statement, which is used to indicate the end of an IBCDMPRS job. 
The JOB statement indicates the beginning of a job. 

The format of the JOB statement is: 

[lattel] JOB [user -information] 

JOB must be preceded and followed by at least one blank. 

The MSG statement defines an output device for operator messages. It follows the 
JOB statement and precedes any function definition statements. 

The format of the MSG statement is: 

[label] MSG TODEV = xxxx 
,TOADDR = ct;u 
where: 

TODEV = xxxx 

specifies the type of the output device to receive messages, for example, 1403. 
The devices that can be specified are 1403, 1443, 1052, 2400, 3210, and 3211. 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the message output 
device. 

The DUMP statement is used to identify both the source volume whose contents are 
to be dumped and the receiving volume. The data contents of the entire source 
volume are dumped, including any data on alternate tracks. If both the source and 
receiving volumes reside on 2311, 2314, 2319, or 3330 volumes, the receiving 
volume is an exact replica of the source volume. 
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The format of the DUMP statement is: 

; [/abe/] DUMP FROMDEV = xxxx 

I .FROMADDR = cuu 

j JODEV = xxxx 

I JOADDR = cuu 

1 [,VOLID = serial[,serialj] 

I [.MODE = mm] 

\ ism^d] 

[.MODEL = n] 
where: 

FROMDEV = xxxx 

specifies the type of the source device, for example, 3330. 

FROMADDR = cuu 

specifies channel number, c, and unit number, uu, of the source device. 

TODEV = xxxx 

specifies the type of the receiving device, for example, 2400. If the receiving 
device is a tape drive and no MODE parameter is specified, the data is written at 
the highest density supported by the device. (For 7-track tape, the default mode is 
93.) 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the receiving device. 

VOLID = serial[,serial]... 

specifies the volume serial numbers of the receiving volumes to which data is to be 
dumped. VOLID is required when the receiving volume has been initialized to 
operating system specifications. If serial does not match the volume serial number 
found on the receiving volume, the operator is notified and the job is terminated. If 
VOLID is not specified and the receiving volume contains a volume serial number, 
the operator is notified. 

MODE = mm 

specifies the bit density for data written onto the receiving magnetic tape volume. 
This parameter is applicable to 7-track tape drives and to 9-track tape drives with 
density selections of 800 and 1600 bits per inch. Valid modes for 7-track tape are 
shown in Table 5. (Only those modes that set the data converter on are accepted.) 
For 9-track tape with density selections of 800 and 1600 bits per inch, the mode 
settings are CB and C3, respectively. If the receiving device is not a tape drive, the 
MODE parameter is ignored. If the receiving device is a tape drive but no mode is 
specified, the data is written at the highest density supported by the device. 

BIN = d 

specifies the decimal number of a bin to be dumped. The value of d can be 
through 9. This parameter applies only to 2321 volumes. When a 2321 volume is to 
be dumped to a 2311, 2314, 2319, or 3330 volume, d must be 0. 

MODEL = n 

specifies a decimal model number (1 or 2) for a 2305. This parameter is applicable 
only when a 2305 is specified. If MODEL is omitted, 2305-1 is assumed. 

Note: The 2319 disk is functionally equivalent to the 2314 disk. To use the 2319, 
specify 2314. 

Dump time can be minimized by selecting devices assigned to different channels. For 
example: 

DUMP FROMDE V= 3330, FROMADDR= 150, TODEV= 2400, TOADDR= 282 

Table 5 shows valid modes for 7-track tape that can be entered for the MODE 
parameter. 

Table 5. Valid 7-Track Tape Unit Modes in IBCDMPRS 



Mode 
(mm) 


Density 
(bits-per-incli) 


Translator 


Data 
Converter 


Parity 


13 


200 


Off 


On 


Odd 


53 


556 


Off 


On 


Odd 


93 


800 


Off 


On 


Odd 
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VDRL Statement 



RESTORE Statement 



The VDRL (volume dump/restore limits) statement is used to specify the upper and 
lower limits of a partial dump. If a track within these limits has had an alternate 
assigned to it, the data on the alternate track is included in the dump. When the VDRL 
statement is used, it must be preceded by a DUMP statement and must be followed by 
an END statement. 

The format of the VDRL statement is: 

[ [/abe/]VDRL BEGIN = nnnnn 

|_^^^^,,^, ^^^ ^^ ,[,ENp= nrinnn]_^^ _ ^^^^ __^^^^ _ 

where: 

BEGIN = nnnnn 

specifies a one- to five-byte relative track address that identifies the first track to 
be dumped. 

END = nnnnn 

specifies the relative track address of the last track to be dumped. If only one track 
is to be dumped, this address is the same as the beginning address. If END is 
omitted, the last track of the volume, excluding those tracks reserved as alternates, 
is assumed to be the upper limit. 

The RESTORE statement is used to identify both the source volume whose data 
contents are to be restored and the receiving volume. 

Note: IBCDMPRS can be used to restore a tape created by lEHDASDR. Conversely, 
lEHDASDR can be used to restore a tape created by IBCDMPRS. 

The format of the RESTORE statement is: 



[labef] RESTORE 



FROMDEV = xxxx 
.FROMADDR = cuu 
.TODEV = xxxx 
.TOADDR = cuu 
,VOLID = serial 
[.MODE = mm] 
[,BIN = d] 
[.MODEL = n] 



where: 



FROMDEV = xxxx 

specifies the type of the source device, for example, 2400. 

FROMADDR = cuu 

specifies the channel number, c, and unit number, uu, of the source device. 

TODEV = xxxx 

specifies the type of the receiving device, for example, 3330. This device type must 
be the same as the device containing the volume originally dumped. 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the receiving device. 

VOLID = serial 

specifies the volume serial number of the receiving volume. If serial does not match 
the volume serial number found on the receiving volume, the operator is notified 
and the job is terminated. 

MODE = mm 

specifies the bit density for data written to the receiving tape volume. This 
parameter must match the mode specified when data was written to the source 
volume. MODE should not be specified if the source and receiving volumes are not 
tape or if MODE was not specified when data was written to the source volume. 
Valid modes are shown earlier in Table 5. (Only those modes that set the data 
converter on are accepted.) For 9-track tape drives with density selections of 800 
and 1600 bits per inch, the mode settings are CB and C3, respectively. 

BIN = cf 

specifies the decimal number of a bin to be restored. This parameter applies only 
to 2321 volumes. The value of d can be through 9. When a 2311, 2314, 2319, 
2301, 2302, 2303, 2305, or 3330 volume is to be restored to a 2321 volume, d 
must be 0. 

MODEL = n 

specifies a decimal model number (1 or 2) for a 2305. If MODEL is omitted, 
2305-1 is assumed. 
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Restore time can be minimized by selecting devices assigned to different channels. For 
example: 

RESTORE FROMDEV = 2400,FROMADDR = 282,TODEV = 3330,T0ADDR = 150 

The END statement marks the end of job. It appears after the last function definition 
statement. 

The format of the END statement isj; 

; [/abe/] END [user-mformaf/on] i 

END must be preceded and followed by at least one blank. 

The examples that follow Illustrate some of the uses of IBCDMPRS. Table 6 can be 
used as a quick reference guide to the examples. The numbers in the "Example" 
column point to examples that follow. 



IBCDMPRS Example 1 



IBCDMPRS Example 2 



Table 6. IBCDMPRS Example Directory 

Operation Comments Example 

DUMP A direct access volume is to be 

dumped to a tape volume. 1 

RESTORE A data set dumped to tape is to be 

restored to a direct access volume. 2 

In this example, a direct access volume is dumped to a tape volume. 
The example follows: 

DUMP 



END 



JOB DUMP 3330 ONTO TAPE 
MSG TODEV=1052,TOADDR=009 
DUMP FROMDEV=3330,FROMADDR=150, 
TODEV=2400 , TOADDR=280 



lie 



In this example, dumped data is restored to a direct access volume. 

The example follows: 

RESTORE JOB RESTORE 3330 FROM TAPE 
MSG TODEV=1052,TOADDR=009 
RESTORE FROMDEV=2400 , FROMADDR=280 , TODEV=3330 , 
TOADDR=150,VOLID=PZ1 11 1 
END 



lie 
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IBCRCVRP is an independent utility used to retrieve usable data from a defective 
track, to assign an alternate track, and to merge the usable data with replacement 
data on the alternate track. (See "Introduction" for general independent utility 
information.) IBCRCVRP will perform the recovery function on only the following 
devices: 2302, 2303, 2311, 2314, 2319, 2321. 

IBCRCVRP is not supported on MP65 with the mode switch set to MS; the mode 
switch must be set to 65. 

Note: lEHATLAS, a system utility program, can be used to perform these operations 
under control of the operating system. 

IBCRCVRP can be used to retrieve data from a defective track, write this data on a 
receiving tape, and list the bad records on the message output device. 

IBCRCVRP can be used to merge data recovered from a defective track with 
replacement data and write the result on an assigned alternate track. (Alternate tracks 
must be assigned manually on drum volumes.) 

A replacement record is an 80-byte card image that contains replacement data for 
bad fields. 

A replacement record must be supplied if a key or data field is found to be bad. The 
replacement record Is described by column, as follows: 

• Columns 1 through 8 contain either "l/D = xxx" or "l/D = LAST". The value of l/D 
must be the same as that of the RECORD parameter of the associated INSERT 
statement. See "INSERT Statement" below. 

• Columns 9 and 10 are blank. 

• Columns 11 through 80 contain replacement data in hexadecimal. The number of 
bytes must be the same as that specified in the COUNT parameter of the INSERT 
statement. See "INSERT Statement" below. 

Replacement records can be continued. The continuation records must start in column 
11 with the continued replacement data. 

When the same device is used to read both control statements and replacement 
records, a replacement record must follow the INSERT statement that describes it. 

IBCRCVRP uses as input: 

• A control data set, which contains utility control statements. 

• A data set from which usable data on a defective track is to be recovered or a data 
set on which bad data is to be replaced. 

• Replacement data if bad data is to be replaced on a data set. 
IBCRCVRP produces as output: 

• A data set from which usable data has been recovered or a data set on which bad 
data has been replaced. 

• A message data set. 

IBCRCVRP is controlled by utility control statements. Because IBCRCVRP is an 
independent utility, operating system job control statements are not used. 

IBCRCVRP utility control statements are: 

• JOB statement, which is used to begin an IBCRCVRP job. 

• MSG statement, which is used to define an output device for operator messages. 

• RECOVER statement, which is used to identify the direct access volume that 
contains the defective track, the defective track, and a receiving volume. 

• LIST statement, which is used to request that the contents of the defective track be 
listed. 

• REPLACE statement, which is used to identify the tape device on which the volume 
containing recovered data resides and the direct access volume on which 
recovered data is to be merged with replacement data. 

• INSERT, which identifies the device on which the replacement record volume 
resides. 



END statement, which is used to indicate the end of an IBCRCVRP job. 
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JOB Statement 



MSG Statement 



RECOVER Statement 



The JOB statement indicates the beginning of an IBCRCVRP job. 

The format of the JOB statement is: 

[^ ijabel} JOB [user information] 

JOB must be preceded and followed by at least one blank. 

The MSG statement defines an output device for operator messages. It follows the 
JOB statement and precedes any function definition statements. 

The format of the MSG statement is: 

[label] MSG TODEV = xxxx 
JOADDR = cuu 
[.MODE = mm] 
where: 

TODEV = xxxx 

specifies the type of the output device to receive messages, for example, 1403. 
The devices that can be specified are 1403, 1443, 1052, and 2400. 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the message output 
device. 

MODE = mm 

specifies the mode in which the message output tape is to be written. This 
parameter is valid only when the message output device is 7-track tape. Valid 
modes are shown in Table 7. If MODE is omitted, the following assumptions (6B) 
are made: density is 556 bits per inch, translator is on, data converter is off, and 
the parity is even. 

Table 7 shows the values that can be entered for the MODE parameter. 
Table 7. Valid 7-Track Tape Unit Modes in IBCRCVRP 



Mode 


Density 




Data 




(mm) 


(bits per incti) 


Translator 


Converter 


Parity 


13 


200 


Off 


On 


Odd 


23 


200 


Off 


Off 


Even 


33 


200 


Off 


Off 


Odd 


2B 


200 


On 


Off 


Even 


3B 


200 


On 


Off 


Odd 


53 


556 


Off 


On 


Odd 


63 


556 


Off 


Off 


Even 


73 


556 


Off 


Off 


Odd 


6B 


556 


On 


Off 


Even 


78 


556 


On 


Off 


Odd 


93 


800 


Off 


On 


Odd 


A3 


800 


Off 


Off 


Even 


B3 


800 


Off 


Off 


Odd 


AB 


800 


On 


Off 


Even 


BB 


800 


On 


Off 


Odd 



The RECOVER statement Identifies: (1) the direct access volume that contains the 
defective track, (2) the defective track, and (3) a receiving tape. A RECOVER 
statement is required for each defective track from which data is to be recovered. The 
RECOVER statement must precede any associated LIST or INSERT statements when 
IBCRCVRP is used to recover data. 



The format of the RECOVER statement is: 

[label] RECOVER FROMDEV = xxxx 
.FROMADDR = cuu 
,TODEV = xxxx 
.TOADDR = cuu 
.VOLID = serial 
.TRACK = bbbbcccchhhh 
[.MODE = mm] 
where: 

FROMDEV = xxxx 

specifies the type of direct access device that contains the defective track, for 
example, 2311. 
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FROMADDR = cuu 

specifies the channel number, c, and unit number, uu, of the direct access device 
that contains the defective tracl<. 

TODEV = xxxx 

specifies the type of the receiving tape volume. If is not specified, the data is 
written at the highest density supported by the device, 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the receiving tape volume. 
This tape must be different from other receiving tapes in the same job. If this 
volume has no label or a if this volume is unlabeled or non standard labeled, the 
RECOVER routine writes a tape mark preceding the data. 

VOLID = serial 

specifies the volume serial number of the direct access volume that contains the 
defective track. If serial does not match the volume serial number found on the 
specified volume, the operator is notified and the job is terminated. 

TRACK = bbbbcccchhhh 

specifies the hexadecimal bin, cylinder, and head addresses of the defective track. 
If the specified track is one for which an alternate has been assigned, data is 
recovered from the alternate, and a message identifying both tracks is issued. 

MODE = mm 

specifies the bit density for data written to the receiving tape volume. This 
parameter is applicable to 7-track tape drives and to 9-track tape drives with 
density selections of 800 and 1600 bits per inch. Valid 7-track modes are shown 
earlier in Table 7. (Only those modes that set the data converter on are accepted.) 
For 7-track tape, the default mode is 93. For 9-track tape drives with 800 and 
1600 bits per inch density selections, the mode settings are CB and C3, 
respectively. If no mode is specified, the data is written at the highest density 
supported by the device. 

REPLACE Statement The REPLACE statement identifies both the tape device containing recovered data 

(recover tape) and the direct access volume on which recovered data is merged with 
new replacement data. 

The forjmat of the REPLACE statement is: 

I [/abe/J REPLACE FROMDEV = xxxx \ 

; .FROMADDR = cuu J 

I JODEV = xxxx i 

! JOADDR = cuu ; 

I ,VOLID = ser/a/ j 

I .TRACK == bbbbcccchhhh I 

where: 

FROMDEV = xxxx 

specifies the type of the device on which the recover tape is mounted, for example, 
2400. If MODE is not specified in this statement, it is assumed that the recover 
tape was written at maximum density. 

FROMADDR = cuu 

specifies the channel number, c, and the unit number uu of the tape device on 
which the recover tape is mounted. 

TODEV = xxxx 

specifies the device type of the direct access device on which recovered data is to 
be merged with replacement data. 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the direct access device 
on which recovered data is to be merged with replacement data. 

VOLID = serial 

specifies the volume serial number of the direct access volume on which recovered 
data is to be merged with replacement data. 

TRACK = bbbbcccchhhh 

specifies the hexadecimal bin, cylinder, and head addresses of the defective 
primary track from which data was recovered. 
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LIST Statement 



INSERT Statement 



MODE = mm 

specifies the bit density at wiiich data was written onto tlie source magnetic tape 
volume. IVIODE should not be specified if it was not specified when data was written 
onto the source volume. Valid 7-track modes are shown earlier in Table 7. (Only 
those modes that set the data converter on are accepted.) For 9-track tape drives 
with 800 and 1600 bits per inch density selections, the mode settings are CB and 
C3, respectively. 

The LIST statement specifies that the entire contents of a defective track be printed 
when data is being recovered; it specifies that both recovered data and replacement 
records are to be listed after they are merged when data is being replaced. If the LIST 
statement is omitted, only bad records are printed when data is being recovered; only 
replacement records are listed when data is being replaced. 

The format of the LIST statement is: 

[label] LIST TODEV = xxxx 
.TOADDR = cuu 
[.MODE = nn] 
where: 

TODEV = xxxx 

specifies the type of the list device, for example, 1403. 

TOADDR = cuu 

specifies the channel number, c, and unit number, uu, of the list device. 

MODE = mm 

specifies the mode in which the list tape is to be written when the list device is 
7-track tape. Valid modes are shown earlier in Table 7. If MODE is not specified 
and the list device is different from the message output device, MODE = 93 is 
assumed. For 9-track tape drives with 800 and 1600 bits per inch density 
selections, the mode settings are CB and C3, respectively. 

Tape volumes must have either a standard label or a tape mark in place of a label. The 
label or tape mark must be written in the same mode as the data. 

If the list device and the message output device are the same, the list mode will be 
the same as the message mode. 

Neither the list device nor the message output device can be the same as the tape 
device containing recovered data. 

The INSERT statement identifies the device that contains each replacement record 
and describes the count field of that record. INSERT statements and corresponding 
data must be in sequence by record number (for example, if records 3 and 5 are bad, 
the INSERT statement and replacement data for record 3 must precede the INSERT 
statement and data for record 5). 

The format of the INSERT statement is: 

[label] INSERT [FROMDEV = xxxx] 
[.FROMADDR = cuu] 
{.RECORD = nnn } 
{.RECORD = LAST} 
.COUNT = cccchhhhrrkkdddd 
[.MODE = mm] 
[.OVERFLOW = YES] 
where: 

FROMDEV = xxxx 

specifies the device type of the device th^t contains replacement data. FROMDEV 
may be omitted if the bad record did not contain key or data fields. 

FROMADDR = cuu 

specifies the channel number, c, and unit number, uu, of the device that contains 
replacement data. FROMADDR may be omitted if the bad record did not contain key 
or data fields. 

RECORD = nnn 

indicates the decimal record number of the original bad record. (This number is 
obtained from message IBC305I.) 
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END Statement 



IBCRCVRP Examples 



RECORD = LAST 

specifies that this replacement record is to be the last physical record written on 
the alternate track. Records can be added after this record if the track capacity is 
not exceeded. With this feature, records near the end of a defective track that has 
missing address markers (and, thus, could not be recovered) can still be replaced. 

COUNT = cccchhhhrrkkdddd 

specifies in hexadecimal the count field for the replacement record, where cccc is 
the cylinder number, hhhh is the head number, rr is the physical record number, kk 
is the key length, in bytes, and dddd is the data length (excluding the key length), in 
bytes. 

MODE = mm 

specifies the mode in which the input tape was written when the replacement data 
is on 7-track tape. Valid modes are shown earlier in Table 7. This tape volume must 
have either a standard label or a tape mark in place of a label. The label or tape 
mark must be written in the same mode as the data. If MODE is omitted, 93 is 
assumed. For 9-track tape drives with 800 and 1600 bits per inch density 
selections, the mode settings are OB and C3, respectively. 

OVERFLOW = YES 

specifies that the bad record, which is being replaced, was a segment, other than 
the last segment, of an overflow record. The replacement record will be either the 
last record or the only record on the assigned alternate track. Six lines per inch are 
to be printed. Channel 1 is assigned to line 4, channel 2 is assigned to line 10, 
channel 3 is assigned to line 16, etc. 

The END Statement denotes the end of job. It appears after the last function definition 
statement. 

The format of the END statement is: 

[label] END [user-information] 

END must be preceded and followed by at least one blank. 

The examples that follow illustrate some uses of IBCRCVRP. Table 8 can be used as a 
quick reference guide to IBCRCVRP examples. The numbers in the "Example" column 
point to the examples that follow. 



IBCRCVRP Example 1 



Table 8. IBCRCVRP Example Directory 

Operation Comments Example 
RECOVER Data is to be recovered from defective tracks on 2314 volumes. 1 

REPLACE Bad data on a 2314 volume is to be replaced. 2 

In this example data is recovered from defective tracks on 2314 volumes 123456 and 
222222. The entire contents of these tracks are listed on a 1403 printer — channel 0, 
unit OE. Note that column 1 is blank. 

The example follows: 



JOB 
MSG 
RECOVER 

LIST 
RECOVER 

LIST 
END 



'RECOVER 2314 TRACKS' 
T0DEV=1 403 , TOADDR=00E 
FROMDE V= 2314, FROMADDR= 190, TODE V= 2400, 

VOLID= 1 23456 , TRACK=0000005E0008 , TOADDR=280 
T0DEV=1 403 , TOADDR=00E 
FROMDEV=23 1 4 , FR0MADDR=1 9 1 , TODEV=2400 , 

TOADDR=281 , VOLID=222222 , TRACK=0000001 10005 
TODEV= 1403, TOADDR=00E 



nc 
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IBCRCVRP Example 2 



JOB 
MSG 
REPLACE 

LIST 
INSERT 

I/D=001 
INSERT 

I/D=003 

END 



In this example, bad data is replaced on 2314 volume 123456. Replacement records 
001 and 003 contain 32 (20 in hexadecimal) bytes and 40 bytes (including an 8-byte 
key) of replacement data, respectively. Record 003 must be continued on an 
additional card image because the replacement data exceeds 35 bytes. Note that 
column 1 is blank for all but the replacement record statements. 

The example follows: 

'REPLACE 2314 TRACK' 
TODE V= 1403, TOADDR= E 
FROMDEV= 2400, FROMADDR= 280, TODE V= 2311, C 

T0ADDR=1 90, V0LID=1 23456, TRACK=0000005E0008 
TODE V= 1 4 3 , TOADDR= E 

FROMDEV=1442,FROMADDR=00C,RECORD=001 , C 

COUNT=005E00080 1 000020 
ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0 123456789 
FROMDEV= 1 442 , FROMADDR=00C , RECORD=003 , C 

COUNT=005E000803080020 
FFFFFFFFFFFFFFFFDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD 
DDDDDDDDDD 
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ICAPRTBL Program 



Input and Output 

Control 

Utility Control Statements 



JOB Statement 



DFN Statement 



UCS Statement 



ICAPRTBL is an independent utility used to load the Universal Character Set (UCS) 
buffer and the forms control buffer (FCB) for an IBM 3211 Printer. (See 
"Introduction" for general Independent utility information.) 

ICAPRTBL is used when the 3211 is assigned as the output portion of a composite 
console and an unsuccessful attempt has been made to initialize the operating system 
because the UCS and FCB buffers contain improper bit patterns. ICAPRTBL is used to 
properly load the buffers so the operating system can be initialized. 

Note: When an operable console printer-keyboard is available, the buffers are loaded 
under the control of the operating system. 

ICAPRTBL uses as input utility control statements that contain images to be loaded 
into the Universal Character Set and/or forms control buffer. ICAPRTBL produces as 
output properly loaded UCS and FCB buffers. 

ICAPRTBL is controlled by utility control statements. Because ICAPRTBL is an 
independent utility, operating system |ob control statements are not used. 

ICAPRTBL utility control statements are: 

• JOB statement, which is used to indicate the beginning of an ICAPRTBL job. 

• DFN statement, which is used to define the address of the 3211. 

• UCS statement, which contains an image of the characters to be loaded into the 
UCS buffer. 

• FCB statement, which defines the image to be loaded into the FCB. 

• END statement, which is used to indicate the end of an ICAPRTBL job. 
The JOB statement indicates the beginning of an ICAPRTBL job. 

The format of the JOB statement is: 

\ [label] JOB luser- information] 

JOB must be preceded and followed by at least one blank. 

The DFN statement is used to define the address of the 3211 and to specify 
lowercase letters are to be printed in uppercase when the lowercase print train is not 
available. 

The format of the DFN statement is: 

[■™™D^"AbbR='cuu,FOLD= {¥'}""■■■" ,-— -^-^ „^„„„„™_^..,_„..„^, 

j . .(N) ^ .' ; . ■ ■ ;.J 

where: 

ADDR = cuu 

specifies the channel number, c, and unit number, uu, of the 3211. 

FOLD = 

specifies whether lowercase letters are to be printed as uppercase letters when the 
lowercase print train is not available. These values can be coded: 

Y 

specifies that lowercase letters are to be printed as uppercase letters when the 
lowercase print train is not available. 

N 

specifies that lowercase letters are not to be printed as uppercase letters. 

The UCS statement contains an image to be loaded into the UCS buffer. 

The format of the UCS statement is: 

[ ucsnameUCS ucs-/mage 

where: 

ucsname 

is a one- to eight-character alphameric name. This name is printed on the printer 
to serve as a reference to the print train being used. 
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FCB Statement 



ucs-image 

specifies characters to be loaded into the UCS buffer. The characters must be 
contained in columns 16 through 71. The first UCS statement contains the first 56 
characters; subsequent statements contain continuations of the image to be loaded 
into the UCS buffer. 

The FCB statement defines the image to be loaded into the forms control buffer. The 
FCB statement may precede or follow the UCS statement. 

The format of the FCB statement is: 

r Yf cbnameTf Wm'^ ' {Gf '''' ''''' " " "'""" " " '" "~" """'" "'""" 

; {8 } 

\ ,LNCH = ((/,c)[,(/,c,)...]) ; 

j ,FORMEND = x ; 

where: 

fcbname 

specifies a one- to eight-character name of the image loaded into the forms 
control buffer. The actual image loaded into the buffer is not affected by this name, 
but to serve as a meaningful reference when printed on the printer, fcbname should 
be the same as the FCB image being used. 

LPI = 

specifies the number of lines per inch that will be printed on the document. These 
values can be coded: 



specifies that six lines per inch will be printed. 



END Statement 



ICAPRTBL Example 



8 



specifies that eight lines per inch will be printed. 

LNCH = 

specifies the channels of the FCB image. Each set of parentheses must contain the 
line number (1-280), a comma, and the channel number (1-12) to be assigned to 
that line. One or all of the 12 channels may be assigned in any order. Each set must 
be separated by commas and the entire group surrounded by parentheses. 

FORMEND = X 

specifies the number of lines (maximum 180) on the printer form. For an 11 inch 
form, spacing six lines per inch, x must be 66. 

The END statement signals the end of the ICAPRTBL job. 

The format of the END statement is: 

[label] END [user -information] 

END must be preceded and followed by at least one blank. 

In this example, an All UCS image and an FCB image are loaded into the UCS and 
FCB buffers. 



The example follows: 

JOB LOAD A1 1 IMAGE 
DFN ADDR=002,FCLD=N 
A1 1 UCS 1<.=IHGFEDCBA*$-RQPONMLKJ%,£ZYXWVUTS/a#0987654321<.=IHGF 
EDCBA*$-RQPONMLKJ%, £ZYXWVUTS/S#098765432 1< .=IHGFEDCBA*$- 
RQPONMLKJ% , £ZYXWVUTS/a#098765432 1 < . =IHGFEDCBA*$-RQPONMLK 
J%, &ZYXWVUTS/a#098765432 1 < . =IHGFEDCBA*$-RQPONMLKJ% , SZYXW 
VUTS/a#0987654321<.=IHGFEDCBA*$-RQPONMLKJ%, £ZYXWVUTS/a#0 
987654321 < . =ihgf edcba*$-rqponmlkj % , £zyxwvuts/23098765432 
1 < . =IHGFEDCBA*$-RQPONMLKJ% , gZYXWVUTS/a#098765432 1 < . =IHGH 
EDCBA*$-RQPONMLKJ%, £ZYXWVUTS/a#098765432 
STD2 FCB LPI=6, C 

LNCH=((4,1 ),( 10,2), ( 16, 3), (22, 4), (28,5), (34,6), (40,7), C 
(46,8),(52,10),(58,11 ),(64,12),(66,9)) 
END 

The control statements are discussed below: 

• DFN specifies the channel and unit number of the 3211 and specifies that 
lowercase letters are not to be printed as uppercase letters when the lowercase 
print train is not available. 

• UCS specifies the characters to be loaded into the UCS buffer. 

• FCB specifies the values to be loaded into the forms control buffer. 
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lEBCOMPR is a data set utility used to compare two sequentially organized or two 
partitioned data sets at the logical record level to verify a backup copy. Fixed, 
variable, or undefined records from blocked or unblocked data sets or members can 
be compared. (See "Introduction" for general data set utility information.) 

Two sequential data sets are considered equal, that Is, are considered to be identical, 
if: 

• The data sets contain the same number of records. 

• Corresponding records and keys are identical. 

If these conditions are not met, an unequal comparison results. If records are unequal, 
the record and block numbers, the names of the DD statements that define the data 
sets, and the unequal records are listed in a message data set. Ten successive 
unequal comparisons terminate the job step unless a user routine is provided to 
handle error conditions. 

Two partitioned data sets are considered equal if: 

• Corresponding members contain the same number of records. 

• Note lists are in the same position within corresponding members. 

• Corresponding records and keys are identical. 

If these conditions are not met, an unequal comparison results. If records are unequal, 
the record and block numbers, the names of the DD statements that define the data 
sets, and the unequal records are listed in a message data set. After ten successive 
unequal comparisons, processing continues with the next member unless a user 
routine is provided to handle error conditions. 

Partitioned data sets can be compared only if all the names in one or both of the 
directories have counterpart entries in the other directory. The comparison is made on 
members identified by these entries and corresponding user data. 

Figure 3 shows the directories of two partitioned data sets. Directory 2 contains 
corresponding entries for all the names in Directory 1; therefore, the data sets can be 
compared. 





Directory 2 

;a8C d;e fgih 



Figure 3. Partitioned Directories Whose Data Sets Can Be Compared Using 
lEBCOMPR 

Figure 4 shows the directories of two partitioned data sets. Each directory contains a 
name that has no corresponding entry in the other directory; therefore, the data sets 
cannot be compared, and the job step is terminated. 





Difectorv 1 

A B}C F H I J 



Directory 2 

A B FISH I J 



Figure 4. Partitioned Directories Whose Data Sets Cannot Be Compared Using 
lEBCOMPR 
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Input and Output 



Control 



Job Control Statements 



User exits are provided for optional user routines to process user labels, handle error 
conditions, and modify source records. See "Appendix A: Exit Routine Linkage" for a 
discussion of the linkage conventions to be followed when user routines are used. 

At the completion or termination of lEBCOMPR, the highest return code encountered 
within the program is passed to the calling program. 

lEBCOMPR uses the following input: 

• Two sequential or two partitioned data sets to be compared. 

• A control data set that contains utility control statements. This data set is required 
if the input data sets are partitioned or if user routines are used. 

lEBCOMPR produces as output a message data set that contains informational 
messages (for example, the contents of utility control statements), the results of 
comparisons, and error messages. 

lEBCOMPR provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 08, which indicates an unequal comparison. Processing continues. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

• 16, which indicates that a user routine passed a return code of 16 to lEBCOMPR. 
The job step is terminated. 

lEBCOMPR is controlled by job control statements and utility control statements. The 
job control statements are required to execute or invoke lEBCOMPR and to define the 
data sets that are used and produced by lEBCOMPR. The utility control statements are 
used to indicate the input data set organization (that is, sequential or partitioned), to 
identify any user routines that may be provided, and to indicate whether user labels 
are to be treated as data. 

Table 9 shows the job control statements necessary for using lEBCOMPR. 
Table 9. lEBCOMPR Job Control Statements 



Restrictions 



Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = lEBCOMPR) or, if the job control statements 

reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set, which can be written to a system output 
device, a tape volume, or a direct access volume. 

SYSUTl DD Defines an input data set to be compared. 

SYSUT2 DD Defines an input data set to be compared. 

SYSIN DD Defines the control data set or specifies DUMMY if the input data sets are 

sequential and no user routines are provided. The control data set normally 
resides in the input stream; however, it can be defined as a member within a 
library of partitioned members. 

The minimum region size that can be specified for lEBCOMPR is 14K + 2b, where b is 
the largest block size in the job step, rounded to the next higher 2K. 

One or both of the input data sets can be passed from a preceding job step. 

Input data sets residing on different device types can be compared. Input data sets 
with a sequential organization written at different densities can be compared. 

• The SYSPRINT DD statement must be present for each use of lEBCOMPR. 

• The SYSIN DD statement is required. 

• The logical record lengths of the input data sets must be identical; otherwise, 
unequal comparisons result. The block sizes of the input data sets can differ; 
however, block sizes must be multiples of the logical record length. 

• The block size specified in the SYSPRINT DD statement must be a multiple of 121. 
The block size specified in the SYSIN DD statement must be a multiple of 80. 

• When the input/output data set has fixed length, variable length, or variable 
spanned records, the BLKSIZE, RECFM, and LRECL are required. When the data set 
has undefined length records, only BLKSIZE is required. 
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utility Control Statements 



COMPARE Statement 



EXITS Statement 



LABELS Statement 



The utility control statements used to control lEBCOMPR are: 

• COMPARE statement, which is used to indicate the organization of a data set. 

• EXITS statement, which is used to identify user exit routines to be used. 

• LABELS statement, which is used to indicate whether user labels are to be treated 
as data by lEBCOMPR. 

The COMPARE statement is used to indicate the organization of data sets to be 
compared. 

The format of the COMPARE statement is: 

\ [label] COMPARE [TYPORG = {PS} 1 

where: 

TYPORG = 

specifies the organization of the input data sets. If TYPORG is omitted, input data 
sets are assumed to be sequentially organized. The values that can be coded are: 

PS 

specifies that the input data sets are sequential data sets. If nothing is specified, 
PS is assumed. 

PO 

specifies that the input data sets are partitioned data sets. 

The COMPARE statement, if included, must be the first utility control statement. 
COMPARE is required if the EXITS or LABELS statement is used or if the input data 
sets are partitioned data sets. 

The EXITS statement is used to identify any user exit routines to be used. 

The format of the EXITS statement is: 

[label] EXITS [INHDR = routinename] \ 

[,INTLR = routinename] 
[.ERROR = routinename] 

[,PRECOMP = routinename] ] 

where: 

INHDR = routinename 

specifies the symbolic name of a routine that processes user input header labels. 

INTLR = routinename 

specifies the symbolic name of a routine that processes user input trailer labels. 

ERROR = routmename 

specifies the symbolic name of a routine that is to receive control after each 
unequal comparison for error handling. If this parameter is omitted and ten 
consecutive unequal comparisons occur while lEBCOMPR is comparing sequential 
data sets, processing is terminated; if the input data sets are partitioned, 
processing continues with the next member. 

PRECOMP = routinename 

specifies the symbolic name of a routine that processes logical records (physical 
blocks in the case of VS or VBS records longer than 32K bytes) from either or both 
of the input data sets before they are compared. 

The EXITS statement is required if a user exit routine is to be used. If more than one 
valid EXITS statement is included, all but the last EXITS statement are ignored. For a 
discussion of the processing of user labels as data set descriptors, see "Appendix E: 
Processing User Labels." 

The LABELS statement specifies whether user labels are to be treated as data by 
lEBCOMPR. For a discussion of this option, refer to "Processing User Labels as Data" 
in "Appendix E: Processing User Labels." 

The format of the LABELS statement is: 



[label] LABELS [DATA = {YES } 
{NO } 
{ALL ) 
{ONLY }] 
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where: 

DATA = 

specifies whether user labels to be treated as data The values that can be coded 
are: 



YES 



specifies that any user labels that are not rejected by a user's label processing 
routine are to be treated as data. Processing of labels as data stops in 
compliance with standard return codes. If no value is entered, YES is assumed. 



NO 



specifies that user labels are not to be treated as data. 



ALL 



specifies that user labels are to be treated as data regardless of any return 
code. A return code of 16 causes lEBCOMPR to complete processing of the 
remainder of the group of user labels and to terminate the job step. 

ONLY 

specifies that only user header labels are to be treated as data. User header 
labels are processed as data regardless of any return code. The job terminates 
upon return from the OPEN routine. 

Note: LABELS DATA = NO must be specified to make standard user label (SUL) exits 
inactive when input/output data sets with nonstandard labels (NSL) are to be 
processed. 

If more than one valid LABELS statement is included, all but the last LABELS 
statement is ignored. 

The examples that follow illustrate some of the uses of lEBCOMPR. Table 10 can be 
used as a quick reference guide to lEBCOMPR examples. The numbers in the 
"Example" column point to examples that follow. 

Table 10. lEBCOMPR Example Directory 



Data Set 

Operation Organization Devices Comments 

COMPARE Sequential 9-track tape No user routines. Blocked Input. 

COIVIPARE Sequential 7-track tape No user routines. Blocked Input. 

COIVIPARE Sequential 7-track and User routines. Blocked Input. 

9-track tape Different density tapes. 3 

COMPARE Sequential Card Reader, No user routines. Blocked Input. i 

9-track tape 4 

COMPARE Partitioned 2314 Disk No user routines. Blocked input. 5 

COPY (using Sequential 9-track tape No user routines. Blocked Input. 

lEBGENER) and Two job steps; data sets are 

COMPARE passed to second job step. 6 

COPY (using Partitioned 2311 Disk User routine. Blocked input. 

lEBCOPY) and Two job steps; data sets are 

COMPARE passed to second job step. 7 

In this example, two sequential data sets that reside on 9-track tape volumes are to 
be compared. 



Example 
1 
2 



The example follows: 

//TAPETAPE JOB 09#660, SMITH 
// EXEC PGM=IEBCOMPR 



//SYSPRINT DD 

//SYSUT1 DD 

// 

// 

//SYSUT2 DD 

// 
// 
//SYSIN DD 

/* 

Because no user routines are to be used and the input data sets have a sequential 
organization, utility control statements are not used. 



SYSOUT=A 

UNIT=2400,LABEL=( ,NL), 
DCB=(RECFM-FB,LRECL-80,BLKSIZE=2000 ), 
DISP=( OLD , KEEP ) , VOLUME=SER=00 1234 

UNIT=2400 , LABEL=( , NL ) , DISP=( OLD , KEEP 
DCB-( RECFM=FB , LRECL=80 , BLKSIZE=1 040 ) , 
VOLUME=SER=001235 

DUMMY 



48 Utilities (Release 21.7) 



lEBCOMPR Example 2 



lEBCOMPR Example 3 



The control statements are discussed below: 

• SYSUTl DD defines an input data set, which resides on an unlabeled, 9-track tape 
volume. The blocked data set was originally written at 800 bits per inch density. 

• SYSUT2 DD defines an input data set, which resides on an unlabeled, 9-track tape 
volume. The blocked data set was originally written at 800 bits per inch density. 

• SYSIN DD defines a dummy data set. 

In this example, two sequential data sets that reside on 7-track tape volumes are to 
be compared. 

The example follows: 

//TAPETAPE JOB 09#660, SMITH 
// EXEC PGM=IEBCOMPR 



SYSOUT=A 

DSNAME=SET1 ,LABEL=( 2 , SUL) ,DISP=( OLD,KEEP ) , 
VOL=SER=00 1 234 , DCB={ DEN=2 , RECFM=FB , LRECL=80 , 
BLKSIZE=2000 , TRTCH=C ) , UNIT=2400-2 

DSNAME=SET1 ,LABEL=( , SUL) ,DISP=( OLD, KEEP ) , 
VOL=SER=00 1235, DCB=( DEN=2 , RECFM=FB , LRECL=80 , 
BLKSIZE=2000 , TRTCH=C ) , UNIT=2400-2 

* 



//SYSPRINT DD 

//SYSUTl DD 

// 

// 

//SYSUT2 DD 

// 
// 
//SYSIN DD 

COMPARE TYPORG=PS 

LABELS DATA=ONLY 
/* 

The control statements are discussed below: 

• SYSUTl DD defines an input data set, which resides on a labeled, 7-track tape 
volume. The blocked data set was originally written at 800 bits per inch density 
with the data converter on. 

• SYSUT2 DD defines an input data set, which is the first or only data set on a 
labeled, 7-track tape volume. The blocked data set was originally written at 800 
bits per inch density with the data converter on. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COMPARE specifies that the input data sets are sequentially organized. 

• LABELS specifies that only user header labels are to be compared. 

In this example, two sequential data sets written at different densities on different 
device types are to be compared. 

The example follows: 



//TAPETAPE JOB 
// EXEC 

//SYSPRINT DD 
DD 



09#660, SMITH 

PGM= lEBCOMPR 

SYSOUT=A 

DSNAME=SET1 ,LABEL=( , SUL ) ,DISP=( OLD, KEEP ) , 
VOL=SER=001234,DCB=(DEN=1 ,RECFM=FB, LRECL=80 , 
BLKSIZE=320 , TRTCH=C ) , UNIT=2400-2 

DSNAME=SET2 , LABEL=( , SUL ) , DISP=( OLD , KEEP ) , 
DCB-( RECFM=FB, LRECL=80 , BLKSIZE=640 ) , 
VOLUME=SER=001235,UNIT=2400 

* 

TYPORG=PS 

INHDR=HDRS , INTLR=TLRS 

DATA=NO 



//SYSUTl 

// 

// 

//SYSUT2 

// 
// 
//SYSIN 

COMPARE 

EXITS 

LABELS 
/* 

The control statements are discussed below: 



DD 



DD 



SYSUTl DD defines an input data set, which is the first or only data set on a 
labeled, 7-track tape volume. The blocked data set was originally written at 556 
bits per inch density with the data converter on. 

SYSUT2 DD defines an input data set, which is the first or only data set on a 
labeled, 9-track tape volume. The blocked data set was originally written at 800 
bits per inch density. 

SYSIN DD defines the control data set, which follows in the input stream. 

COMPARE specifies that the input data sets are sequentially organized. 
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lEBCOMPR Example 4 



lEBCOMPR Example 5 



lEBCOMPR Example 6 



//SYSIN 


DD 


//SYSUT2 


DD 


// 




// 




//SYSUT1 


DD 



• EXITS identifies the names of routines to be used to process user input header 
labels and trailer labels. 

• LABELS specifies that the user input header and trailer labels are not to be 
compared. 

In this example, two sequential data sets (card input and tape input) are to be 
compared. 

The example follows: 

//CARDTAPE JOB 09#660, SMITH 
// EXEC PGM=IEBCOMPR 

//SYSPRINT DD SYSOUT=A 
DUMMY 

UNIT=2400 , VOLUME=SER=00 1 234 , LABEL=( , NL) , 
DCB=( RECFM=FB , LRECL=80 , BLKSIZE=2000 ) , 
DISP=( OLD, KEEP) 
DATA 

(input card data set) 

/* 

The control statements are discussed below: 

• SYSIN DD defines a dummy control data set. Because no user routines are 
provided and the input data sets are sequential, utility control statements are not 
used. 

• SYSUT2 DD defines an input data set, which resides on an unlabeled, 9-track tape 
volume. The blocked data set was originally written at 800 bits per inch density. 

• SYSUTl DD defines an input data set (card input). 

In this example, two partitioned data sets are to be compared. 
The example follows: 

//DISKDISK JOB 09#660, SMITH 
// EXEC PGM=IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

DSNAME=PDSSET , UNIT=23 1 4 , DISP=( OLD , KEEP ) , 
DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ), 
V0LUME=SER=1 11112 

DSNAME=PDSSET , UNIT=23 1 4 , DISP=( OLD , KEEP ) , 
DCB=(RECFM^FB,LRECL=80,BLKSIZE=2000 ), 
V0LUME=SER=1 11113 
* 

TYPORG=PO 
/* 
The control statements are discussed below: 

• SYSUTl DD defines an input partitioned data set. The blocked data set resides on a 
2314 volume. 

• SYSUT2 DD defines an input partitioned data set. The blocked data set resides on a 
2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set consists of one utility control statement. 

In this example, a sequential data set is to be copied and compared in two job steps. 

The example follows: 

//TAPETAPE JOB 09#660, SMITH 
//STEPA EXEC PGM=IEBGENER 
//SYSPRINT DD SYSOUT=A 



//SYSUTl 
/ / 


DD 


// 
// 




//SYSUT2 


DD 


// 




// 




//SYSIN 


DD 


COMPARE 



DD DSN=COPYSET,UNIT=2400,DISP=( OLD, PASS ), 

DCB=(RECFM=FB,LRECL=80,BLKSIZE=640), 

LABEL=( , SL ) , VOLUME=SER=00 1 234 
DD DSNAME=COPYSET,DISP=( , PASS ) , LABEL=( , SL ) , 

DCB=( RECFM=FB , LRECL=80 , BLKSIZE=640 ) , 

VOLUME=SER=00 1235, UNIT=2400 
DD DUMMY 



//SYSUTl 

// 

// 

//SYSUT2 

// 
// 
//SYSIN 

/* 

//STEPB EXEC PGM-IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=*. STEPA. SYSUTl ,DISP=( OLD, KEEP) 

//SYSUT2 DD DSNAME-*. STEPA. SYSUT2,DISP=( OLD, KEEP) 

//SYSIN DD DUMMY 

/* 
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The first job step copies the data set and passes the original and copied data sets to 
the second job step. The second job step compares the two data sets. 

The control statements for the lEBCOMPR job step are discussed below: 

• SYSUTl DD defines an input data set passed from the preceding job step. The data 
set resides on a labeled, 9-track tape volume. The blocked data set was originally 
written at 800 bits per inch density. 

• SYSUT2 DD defines an input data set passed from the preceding job step. The data 
set, which was created in the preceding job step, resides on a labeled, 9-track tape 
volume. The blocked data set was originally written at 800 bits per inch density. 

• SYSIN DD defines a dummy control data set. Because the input is sequential and no 
user exits are provided, no utility control statements are required. 

lEBCOMPR Example 7 In this example, a partitioned data set is to be copied and compared in two job steps. 

The example follows: 

//DISKDISK JOB 09#660, SMITH 
//STEPA EXEC PGM=IEBCOPY 
//SYSPRINT DD SYSOUT=A 

DD DSNAME=OLDSET,UNIT=2311 ,DISP=( OLD, PASS), 
V0LUME=SER=1 1 1 1 1 2 ,DCB=( RECFM=FB,LRECL=80 , 
BLKSIZE=640 ) 

DSNAME=NEWMEMS , UNIT=2 3 1 1 , DISP= ( , PASS ) , 
V0LUME=SER=1 11113, SPACE=( TRK, (10,5,5)), 
DCB=( RECFM=FB , LRECL=80 , BLKSIZE=640 ) 
UNIT=231 1 ,SPACE=(TRK,( 1 ) ) 
UNIT=231 1 ,SPACE={TRK,( 1 ) ) 
* 
COPY 0UTDD=SYSUT2,INDD=SYSUT1 
SELECT MEMBER=(A,B,D,E,F) 

/* 

//STEPB EXEC PGM=IEBCOiyiPR 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=OLDSET,DISP=( OLD, KEEP) 

//SYSUT2 DD DSNAME=NEWMEMS,DISP=( OLD, KEEP) 

//SYSIN DD * 

COMPARE TYPORG=PO 

EXITS ERROR=SEEERROR 
/* 

The first job step copies the data set and passes the original and copied data sets to 
the second job step. The second job step compares the two data sets. 

The control statements for the lEBCOMPR job step are discussed below: 

• SYSUTl DD defines a blocked input data set that is passed from the preceding job 
step. The data set resides on a 2311 volume. 

• SYSUT2 DD defines a blocked input data set that is passed from the preceding job 
step. The data set resides on a 2311 volume. 

• SYSIN DD defines the control data set, which contains a COMPARE statement and 
an EXITS statement. 

• COMPARE specifies partitioned organization. 

• EXITS specifies that a user routine, SEEERROR, is to be used. 

Because the input data set names are not identical, the data sets can be retrieved by 
their data set names. 



//SYSUTl 


DD 


// 




// 




//SYSUT2 


DD 


// 




// 




//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 
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lEBCOPY Program 



Creating a Backup Copy 



Copying Data Sets 



lEBCOPYI is a data set utility used to copy one or more partitioned data sets or to 
merge partitioned data sets. (See "Introduction" for general data set utility 
information.) Specified members of partitioned data sets can be selected for, or 
excluded from, a copy process. 

lEBCOPY can be used to: 

Create a backup copy. 

Copy data sets. 

Select members, from one or more data sets, to be copied. 

Replace identically named members on data sets. 

Replace selected data set members. 

Rename selected members. 

Exclude members, from one or more data sets, from being copied. 

Compress a data set in place. 

Merge data sets. 

Re-create a data set that has exhausted its primary, secondary, or directory space 
allocation. 

In addition, lEBCOPY automatically lists the number of unused directory blocks and 
the number of unused tracks available for member records in the output partitioned 
data set. The names of copied members can be listed by input partitioned data set. 

When copying members that have aliases, the following should be noted: 

• When the main member and its aliases are copied, they exist on the output 
partitioned data set in the same relationship they had on the input partitioned data 
set. 

• When one alias is copied without its main member, it becomes a main member. 

o When two or more aliases are copied without the main member, the lowest alias (In 
alphameric collating sequence) becomes the main member; any remaining aliases 
become aliases of the new main member. Note that if an old main member name is 
present in an alias entry, it remains there. 

The rules for replacing or renaming members apply to both aliases and members; no 
distinction is made between them. 

At the completion or termination of the program, the highest return code encountered 
within the program is passed to the calling program. 

lEBCOPY can be used to copy a partitioned data set, totally or in part, from one direct 
access volume to another. In addition, a data set can be copied to its own volume, 
provided its data set name is changed. If the data set name is not changed, the data 
set Is compressed in place. 

Note: The copied members are not reordered; that is, they are copied in the order in 
which they exist on the original data set. If the members are to be collated, lEHMOVE 
can be used for the copy operation. See the chapter "lEHMOVE Program" for a 
discussion of the lEHMOVE program. 

lEBCOPY can be used to copy more than one input partitioned data set, totally or in 
part, from one or more direct access volumes to a single direct access volume. See 
"COPY Statement" below for a discussion of how to specify more than one input 
partitioned data set. The input partitioned data sets are copied in the order in which 
they are specified. 



^ This is a description of the version of lEBCOPY available on Release 21.7 of IBM System/360 
Operating System. The program Is designed to accept the job and control statements written for 
the version available on releases prior to Release 20. However, it Is recommended that any 
future user applications be written to the specifications discussed In this chapter. 
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Selecting Members 
to be Copied 



Replacing Identically 
Named Members 



Members can be selected from one or more input partitioned data sets. Selected 
members are searched for in a low-to-high (a to z) collating sequence, regardless of 
the order in which they are specified; however, they are copied in the same physical 
sequence in which they appear on the input partitioned data set. 

When selecting members from an input partitioned data set, remember that once a 
member is found it is not searched for on any subsequent input partitioned data set. 
Similarly, when all of the selected members are found, the copy step is terminated 
although all of the input partitioned data sets may not have been searched. For 
example, if members A and B are specified and A is found on the first of three input 
partitioned data sets, it is not searched for again; if B is found on the second input 
partitioned data set, the copy operation is successfully terminated after the second 
input partitioned data set has been processed, although both A and B may also exist 
on the third input partitioned data set. 

However, if the first member name is not found on the first input partitioned data set, 
the second selected member is searched for; if it is not found, the third is searched 
for, and so on. This process continues until there are no more members to be 
searched for in this input partitioned data set. All the members that were found on the 
input partitioned data set are then processed for copying onto the output partitioned 
data set. This process is repeated for the second input partitioned data set (except 
that the members that were found on the first input partitioned data set are not 
searched for again). 

In many copy operations, the output partitioned data set may contain members that 
have names identical to the names of the input partitioned data set members to be 
copied. When this occurs, the user may specify that the identically named members 
are to be copied from the input partitioned data set to replace existing members. The 
replace option allows an input member to override an existing member on the output 
partitioned data set with the same name. 

If the replace option is not specified, input members are not copied when they have 
the same name as a member on the output partitioned data set. 

The replace option can be specified on the data set or member level. The level is 
specified on a utility control statement. 

When replace is specified on the data set (specified on a COPY or on the INDD 
statement), the input data is copied as follows: 

• In a full copy process, all members on an input partitioned data set are copied onto 
an output partitioned data set; members whose names already exist on the output 
partitioned data set are replaced by the members copied from the input partitioned 
data set. 

• In a selective copy process, all selected members on an input partitioned data set 
are copied to an output partitioned data set; all selected members found are copied 
and members whose names already exist on the output partitioned data set are 
replaced by the found members copied from the input partitioned data set. 

• In an exclusive copy process, all nonexcluded members on input partitioned data 
sets are copied to an output partitioned data set; nonexcluded input members 
whose names already exist on the output partitioned data set replace those 
identically named members on the output partitioned data set. 

When replace is specified on the member level (specified on a SELECT statement), 
only selected members on the input partitioned data sets are copied, and identically 
named members on the output partitioned data set are replaced. 

Differences between full, selective, and exclusive copy processing should be 
remembered when specifying the replace option when multiple data sets contain 
member names common to some or all of the input partitioned data sets being copied. 
These differences are: 

• When a full copy is performed, the output partitioned data set contains the 
replacing members that were on the last input partitioned data set copied. 

• When a selective copy is performed, the output partitioned data set contains the 
selected replacing members which were found on the earliest input partitioned data 
set searched. Once a selected member is found, it is not searched for again; 
therefore, once found, a selected member is copied, and if the same member exists 
on another input partitioned data set it is not searched for, and hence, not copied. 

• When an exclusive copy is performed, the output partitioned data set contains the 
nonexcluded replacing members that were on the last input partitioned data set 
copied. 
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Replacing Selected Members 



Renaming Selected Members 



Excluding Members from 
a Copy Operation 



Compressing a Data Set 



Merging Data Sets 



Re-creating a Data Set 



Input and Output 



Ttie user may specify the replace option on either the data set or the member level 
when members are being selected for copying. 

If the replace option is specified on the data set level, all selected members found on 
the designated input partitioned data sets replace identically named members on the 
output partitioned data set. This is limited by the fact that once a selected member is 
found it is not searched for again. 

If the replace option is specified on the member level, the specified members on the 
input partitioned data set replace identically named members on the output 
partitioned data set. Once a member is found it is not searched for again. (See 
"Replacing Identically Named Members" earlier in this chapter.) 

Selected members on input partitioned data sets can be copied and renamed on the 
output partitioned data set. However, if the new name is identical to a member name 
on the output partitioned data set, the input member is not copied unless the replace 
option is also specified. See "SELECT Statement" below for information on renaming 
selected members. 

Note: Renaming is not physically done to the input partitioned data set directory entry. 
However, after the member is copied onto the output partitioned data set, the new 
name is entered into the output partitioned data set directory. 

Members from one or more input partitioned data sets can be excluded from a copy 
operation. The excluded member is searched for on every input partitioned data set in 
the copy operation and is always omitted from the copy. 

The replace option can be specified on the data set level in an exclusive copy, in 
which case, nonexcluded members on the input partitioned data set replace identically 
named members on the output partitioned data set. See "Replacing Identically Named 
Members" earlier in this chapter for more information on the replace option. 

A compressed data set is one that does not contain embedded unused space. After 
copying one or more input partitioned data sets to a new output partitioned data set 
(by means of a selective, exclusive, or full copy that does not involve replacing 
members), the output partitioned data set contains no embedded unused space. 

To make unused space available, either the entire data set must be scratched or it 
must be compressed in place. A compressed version can be created by specifying the 
same data set for both the input and the output parameters in a full copy step. A 
backup copy of the partitioned data set to be compressed in place should be kept until 
successful completion of an in-place compression is indicated (by an end-of-job 
message and a return code of 00). 

Note: An in-place compression does not release extents assigned to the data set. 

A merged data set is one to which an additional member is copied. It is created by 
copying the additional members to an existing output partitioned data set; the merge 
operation — the ordering of the output partitioned data set's directory — is 
automatically performed by lEBCOPY. 

Note: If there is a question about whether or not enough directory blocks are allocated 
to the output partitioned data set to which an input partitioned data set is being 
merged, the output partitioned data set should he re-created prior to the merge 
operation. 

A data set can be recreated by copying it and allocating a larger amount of space 
than was allocated for the original data set. This application of lEBCOPY is especially 
useful if insufficient directory space was allocated to a data set. Space cannot be 
allocated in this manner for an existing data set into which members are being 
merged. 

lEBCOPY uses the following input: 

• An input data set, which contains the members to be copied or merged into a 
partitioned data set. 

• A control data set, which contains utility control statements. The control data set is 
required if selected members are to be copied, merged into a partitioned data set, 
or omitted from the copy or merge operation. 

If the control data set is null, a full copy is attempted from the input partitioned data 
set to the output partitioned data set. In this case, SYSUTl and SYSUT2 are required 
ddnames for the input partitioned data set and output partitioned data set, described 
under "Job Control Statements" below, respectively. 
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Control 

Job Control Statements 



Note: When merging into or compressing libraries, do not specify DISP = SHR. The 
results of a merge into or compress of the current SYSl.LINKLIB or SYSl.SVCLIB 
would be unpredictable. 

lEBCOPY produces the following output: 

• An output data set, which contains the copied or merged data. The output data set 
is either a new data set (from a copy operation) or an old data set (from a merge 
or compress-in-place). 

• A message data set, which contains informational messages (for example, the 
names of copied members) and error messages, if applicable. 

• Spill data sets, which are temporary data sets used to provide space when not 
enough main storage is available for the input and/or output partitioned data set 
directories. These data sets are opened only when needed. 

All input, output, and utility data sets must be on direct access devices. The following 
devices may be used: 

2311 Disk Storage Drive 

2314 Direct Access Storage Facility 

2319 Direct Access Storage Facility 

2301 Disk Storage 

2302 Drum Storage 

2303 Drum Storage 
2305 Fixed Head Storage 
2321 Data Cell Drive 
3330 Disk Storage 

Any combination of these devices is acceptable to lEBCOPY. 

Note: Refer to OS Storage Estimates, GC28-6551, to determine when spill data sets 
are required; see "Space Allocation" below for a description of how to determine the 
amount of space to allocate.) 

lEBCOPY produces a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates a condition from which recovery may be possible. 

• 08, which indicates an unrecoverable error. The job step is terminated. 

lEBCOPY is controlled by job control statements and utility control statements. 

Table 11 shows the job control statements necessary for using lEBCOPY. 

The minimum region size that can be specified for lEBCOPY is 28K + 2b, where b is 
the largest block size in the job step, rounded to the next higher 2K. For additional 
information, see OS Storage Estimates, GC28-6551. 

Fixed or variable records can be reblocked. Reblocking or deblocking is done if the 
block size of the input partitioned data set is not equal to the block size of the output 
partitioned data set, Reblocking or deblocking cannot be done if either the input or the 
output data set has undefined format records, keyed records, track overflow records, 
note lists, or user TTRNs, or if compress in place is specified. (Earlier versions allowed 
reblocking or deblocking with track overflow output records.) 

Table 12 shows how input record formats can be changed. In addition, any record 
format can be changed to the undefined format (in terms of its description in the 
DSCB). 

System data sets should not be compressed in place in a multiprogramming 
environment unless the subject partitioned data set is made non-sharable. The libraries 
in which lEBCOPY resides (SYSl.LINKLIB and SYSl.SVCLIB) must not be compressed 
by lEBCOPY unless lEBCOPY is first transferred to a JOBLIB. 

Refer to OS Data Management Services Guide, GC26-3746, for information on 
estimating space allocations. 
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Table 11. lEBCOPY Job Control Statements 

Statement Use 

JOB Initiates tlie job. 

EXEC Specifies the program name (PGM = lEBCOPY) or, if the job control statements 

reside in the procedure library, the procedure name. 

SYSPRINT DD Defines the sequential message data set used for listing statements and 

messages. This data set can be written onto a system output device, a tape 
volume, or a direct access volume. 

I anynamel DD Defines an input partitioned data set. The data set can be defined by a data set 
name, as a cataloged data set, or as a data set passed from a previous job step. 

I anyname2 DD Defines an output partitioned data set. 

SYSUT3 DD Defines a spill data set on a direct access device. SYSUT3 is used when there is 
no space in main storage for some or all of the current input partitioned data 
set's directory entries. SYSUT3 may also be used when not enough space is 
available in main storage for retaining information during table sorting. 

SYSUT4 DD Defines a spill data set on a direct access device. SYSUT4 is used when there is 
no space in main storage for the current output partitioned data set's merged 
directory and the output partitioned data set is not new. 

SYSIN DD Defines the control data set. The control data set normally resides in the input 

stream; however, it can reside on a system input device, a tape volume, or a 
direct access volume. 



Table 12. Changing Input Record Format Using lEBCOPY 



Restrictions 



Space Allocation 



Input 

Fixed 

Fixed Blocked 

Variable 

Variable Blocked 



Output 

Fixed Blocked 

Fixed 

Variable Blocked 

Variable 



Refer to OS Storage Estimates, GC28-6551, to determine when spill data sets are 
required; see "Space Allocation" below for a description of how to determine the 
amount of space to allocate. 

• SYSPRINT and SYSIN are mandatory DD statements. The block size for the 
SYSPRINT data set must be a multiple of 121. The block size for the SYSIN data 
set must be a multiple of 80. Any blocking factor may be specified for these data 
sets, with a maximum allowable block size of 32,767 bytes. 

• The SYSPRINT DD statement must define a data set with fixed blocked or fixed 
records. 

• At least one INPUT DD statement is required; there must be one INPUT DD 
statement for each unique part in the data set used for input in the job step. 

• Input data sets cannot be concatenated. 

• There must be an OUTPUT DD statement for each unique partitioned data set used 
for output in the job step. 

• The SYSIN DD statement must define a data set with fixed block or fixed records. 

Sometimes it is necessary to allocate space on spill data sets (SYSUT3 and SYSUT4). 
To conserve space on the direct access volume, an initial quantity and a secondary 
quantity for space allocation may be used, as shown in the following SPACE 
parameter: 

SPACE = (c,(x,y)) 

The c value should be a block length of 80 for SYSUT3 and of 256 for SYSUT4. The x 
value is the number of blocks in the primary allocation, and the y value is the number 
of blocks in a secondary allocation. 

For SYSUT3, x + 15y must be equal to or greater than the number of entries in the 
largest input partitioned data set in the copy operation, multiplied by 1.05. 

For SYSUT4, x + 15y must be equal to or greater than the number of blocks allocated 
to the largest output partitioned data set directory in the lEBCOPY job step. 
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For example, if there are 700 members on the largest input partitioned data set, 
space could be allocated for SYSUT3 as follows: 

SPACE = (80,(60,45)) 

However, the total amount of space required for SYSUT3 in the worst case is used 
only if needed. If space is allocated in this manner for SYSUT4, the user must specify 
in his SYSUT4 DD statement: 

DCB = KEYLEN = 8 

Note that lEBCOPY ignores all other DCB information specified for SYSUT3 and/or 
SYSUT4. Multivolume SYSUT3 and SYSUT4 data sets are not supported. 

lEBCOPY is controlled by the following utility control statements: 

• COPY statement, which indicates the beginning of a COPY operation. 

• SELECT statement, which specifies which members in the input data set are to be 
copied. 

• EXCLUDE statement, which specifies members in the input data set to be excluded 
from the copy step. 

In addition, when INDD, a COPY statement parameter, appears on a card other than 
the COPY statement, it is referred to as an INDD statement; it can function as a 
control statement in this context. 

Utility control statements may be continued on subsequent cards provided that all the 
data is contained in columns 2 through 71. Control statement operation and keyword 
parameters can be abbreviated to their initial letters; for example, COPY can be 
abbreviated to C. 

The COPY statement is required to initiate all lEBCOPY copy operations. Any number 
of COPY statements can appear within a single job step. 

A COPY statement must precede a SELECT or EXCLUDE statement when members are 
selected for or excluded from a copy step. In addition, if an input ddname is specified 
on a separate INDD statement, it must follow the COPY statement and precede the 
SELECT or EXCLUDE statement to which it applies. If one or more INDD statements 
are immediately followed by the /* card or another COPY statement, a full copy is 
invoked onto the most recent output partitioned data set previously specified. 

lEBCOPY uses a copy operation/copy step concept. The unit of work starting with a 
COPY statement and continuing until another COPY statement or until the end of the 
control data set is found is called a copy operation. Within each copy operation, one 
or more copy steps are present. Any INDD statement directly following a SELECT or 
EXCLUDE statement marks the beginning of the next copy step and the end of the 
preceding copy step within the copy operation. If such an INDD statement cannot be 
found in the copy operation, then the operation consists of only one copy step. 

Figure 5 shows the copy operation/copy step concept. Two copy operations are 
shown in the figure: the first begins with the statement containing the name 
COPOPERl, and the second begins with the statement containing the name 
C0P0PER2. 

There are two copy steps within the first copy operation shown in Figure 5: the first 
begins with the COPY statement and continues through the two SELECT statements; 
the second begins with the first INDD statement following the two SELECT statements 
and continues through the EXCLUDE statement preceding the second COPY 
statement. There are two copy steps within the second copy operation: the first begins 
with the COPY statement and continues through the SELECT statement; the second 
begins with the INDD statement immediately following the SELECT statement and ends 
with the same /* (delimiter) statement that ended the copy operation. 

The format of the COPY statement is: 



[label] COPY 



where: 



OUTDD = ddname 

[,INDD= { ddname l[,cfc/name2]... } 

{ddnamel[,ddname2][,{ddname2,R)']'- } 

{({ddnamel,R)[,ddname2]...) }] 

[.LIST = NO] 



OUTDD = ddname 

specifies the name of the output partitioned data set. One ddname is required for 
each copy operation; the ddname used must be specified on a DD statement. 
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Figure 5. Multiple Copy Operations Within a Job Step 



INDD = 

specifies thie names of tlie input partitioned data sets. INDD may, optionally, be 
placed on a separate card following a COPY statement containing the OUTDD 
parameter, another INDD statement, a SELECT statement, or an EXCLUDE 
statement. These values can be coded: 

ddname 

specifies the ddname, which is specified on a DD statement, of an input 
partitioned data set. If more than one ddname is specified, the input data sets 
are processed in the same sequence as the ddnames. 

R 

specifies that all members to be copied from this input partitioned data set are 
to replace any identically named members on the output partitioned data set. (In 
addition, members whose names are not on the output partitioned data set are 
copied as usual.) When this option is specified with the INDD parameter, it does 
not have to appear with the MEMBER parameter (discussed in "SELECT 
Statement" in this chapter) in a selective copy operation. When this option is 
specified, the ddname and the R parameter must be enclosed in a set of 
parentheses; if it is specified with the first ddname in INDD, the entire field, 
exclusive of the INDD parameter, must be enclosed in a second set of 
parentheses. 

LIST = NO 

specifies that the names of copied members are not to be listed on SYSPRINT at 
the end of each input data set. 

Note: The control statement operation and keyword parameters can be abbreviated to 
their initial letters; for example, COPY can be abbreviated to C and OUTDD can be 
abbreviated to 0. 

Only one INDD and one OUTDD keyword may be placed on a single card. OUTDD must 
appear on the COPY statement. When INDD appears on a separate card, no other 
operands may be specified on that card. 

INDD may appear on a separate card; if this option is selected, INDD is not preceded 
by a comma. 

If there are no keywords on the COPY card, compatibility with the previous version is 
implied. In this case, comments may not be placed on this card. 

If more than one ddname is specified, the input partitioned data sets are processed in 
the same sequence as that in which the ddnames are specified. 

A full copy is invoked only by specifying different input and output ddnames; that is, 
by omitting the SELECT or EXCLUDE statement from the copy step. 

The compress-in-place function is normally invoked by specifying the same ddname 
(with the same dsname and volume serial number specified on the DD statement) for 
both the OUTDD and INDD parameters of a COPY statement. If multiple entries are 
made on the INDD statement, a compress in place will occur if one of the input 
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ddnames is the same as the ddname specified by the OUTDD parameter of the COPY 
statement, provided that SELECT or EXCLUDE is not specified. 

The compress-in-place operation cannot be performed for the following: 

• A data set with track overflow records. 

• A data set with keyed records. 

• A data set for which reblocking is specified in the DCB parameter. 

• An unmovable data set. 

When a compression is invoked by specifying the same ddname for the INDD and 
OUTDD parameters, and the DD statement specifies a block size that differs from the 
block size specified in the DSCB, the DSCB block size is overridden; however, no 
physical reblocking or deblocking is done by lEBCOPY. 

The SELECT statement specifies members to be selected from input partitioned data 
sets. This statement is also used to rename and/or replace selected members on the 
output partitioned data set. More than one SELECT statement may be used in 
succession, in which case the second and subsequent statements are treated as a 
continuation of the first. 

The SELECT statement must follow either a COPY statement that includes an INDD 
parameter or one or more INDD statements. A SELECT statement cannot appear with 
an EXCLUDE statement in the same copy operation. 

When a selected member is found on an input partitioned data set, it is not searched 
for again, regardless of whether it is copied. A selected member will not replace an 
identically named member on the output partitioned data set unless the replace option 
is specified on either the data set or member level. (For a description of replacing 
identically named members see "Replacing Identically Named Data Set Members," 
and "Replacing Selected Members" in this chapter.) In addition, a renamed member 
will not replace a member on the output partitioned data set that has the same new 
name as the renamed member, unless the replace option is specified. 

The format of the SELECT statement is: 



[label] SELECT MEMBER 



name... 

[(] (name„R)...[)] 

[(] (name, newname[,R] )...[)] 



[-■] 



where: 



MEMBER = 

specifies the members to be selected from the input partitioned data set. The 
values that can be coded are: 

name 

specifies the name of a member that is to be selected in a copy step. Each 
member name specified within one copy step must be unique; that is, duplicate 
names cannot be specified as either old names, or new names, or both, under 
any circumstances. 

newname 

specifies a new name for a selected member. The member is copied onto the 
output partitioned data set using its new name. If the name already appears on 
the output partitioned data set, the member is not copied unless replacement 
(R) is also specified. 

R 

specifies that the input member is to replace any identically named member that 
exists on the output partitioned data set. 

Note: The control statement operation and keyword parameter can be abbreviated to 
their initial letters; SELECT can be abbreviated to S and MEMBER can be abbreviated 
to M. 

To rename a member, the old member name is specified in the SELECT statement, 
followed by the new name and, optionally, the R parameter. When this option is 
specified, the old member name and new member name must be enclosed in a set of 
parentheses. When any option within parentheses is specified anywhere in the 
MEMBER field, the entire field, exclusive of the MEMBER keyword, must be enclosed in 
a second set of parentheses. 
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The EXCLUDE statement specifies members to be excluded from the copy step. Unlike 
the selective copy, an exclusive copy causes all specified members on each input 
partitioned data set to be excluded from the copy. 

More than one EXCLUDE statement may be used in succession, in which case the 
second and subsequent statements are treated as a continuation of the first. The 
EXCLUDE statement must follow either a COPY statement that includes an INDD 
parameter or one or more INDD statements. An EXCLUDE statement cannot appear 
with a SELECT statement in the same copy step; however, both may be used in a 
single copy operation. 

The format of the EXCLUDE statement is: 

[ llabef] EXCLUDE MEMBER = lQmembernamel[,membername2}..l)} 

where: 

MEMBER = [(]membernamel[,membername2]...[)] 

specifies members on the input partitioned data sets that are not to be copied to 
the output partitioned data set. The members are not deleted from the input 
partitioned data set unless the entire data set is deleted. (This can be done by 
specifying DISP = DELETE in the operand field of the input DD job control 
statement.) Each member name specified within one copy step must be unique. 

Note: The control statement operation and keyword parameter can be abbreviated to 
their initial letters; EXCLUDE can be abbreviated to E and MEMBER can be abbreviated 
toM. 

The following examples illustrate some of the uses of lEBCOPY. Table 13 can be used 
as a quick reference guide to lEBCOPY examples. The numbers in the "Example" 
column point to examples that follow. 



Table 13. lEBCOPY Example Directory 



Operation Device 



COPY 


2314 Disk 


COPY 


2311 Disk, 




2301 Drum, 




2302 Disk 


COPY 


2302 Disk, 




2314 or 2319 Disk^ 


COPY 


2302 Disk, 




2314 Disk, 




2311 Disk 


COPY 


2302 Disk, 




2311 Disk 


COPY 


2301 Drum, 




2314 or 2319 Disk,^ 




2311 Disk 


COPY 


2311 Disk 



Comnnents 

Full Copy. 

Multiple input partitioned data sets. 
Fixed-blocked and fixed record formats. 

All members are to be copied 
Identically named members on the 
output data set are to be replaced. 

Selected members are to be copied. 
Variable blocked data set is to he 
created. Record formats are variable- 
blocked and variable. 

Selected members are to be copied. 
One member is to replace an 
identically named member on the 
output data set. 

Selected members are to be copied. 
Members found on first input data set 
replace identically named members on 
the output data set. 

Selected members are to be copied. 
Two members are to be renamed. One 
renamed member is to replace an 
identically named member on the 
output data set. 



Exannple 
1 



COPY 


2314 Disk 


Exclusive Copy. Fixed blocked and 
fixed record formats. 


8 


COPY 


2314 or 2319 Disk^ 


Compress-in-place. 


9 


COPY 


2311 Disk, 
2314 Disk 


Full copy to be followed by a, compress- 
in-place of the output data set. Replace 
specified for one input data set. 


10 


COPY 


2314 or 2319 Disk 


Multiple copy operations. 


11 


COPY 


2311 Disk 


Multiple copy operations. 


12 


^ The 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 2314 
control statement. 


in the 
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In this example, a partitioned data set (DATASET5) is to be copied from one disk 
volume to another. Figure 6 shows the input and output data sets before and after 
processing. 

The example follows: 



//COPY JOB 
//JOBSTEP EXEC 
//SYSPRINT DD 



//IN0UT4 

// 

//IN0UT5 

// 

//SYSUT3 

//SYSUT4 

//SYSIN 

COPYOPER 

/* 



06#990,MCEWAN 

PGiyi=IEBCOPY 

SYSOUT=A 
DD DSNAME=DATASET4,UNIT=2314,VOL=SER=1 11112, 

DISP=(NEW,KEEP),SPACE=(TRK,(5,1 ,2) ) 
DD DSNAME=DATASET5 , UNIT=23 1 4 , VOL=SER= 111113, 

DISP=OLD 
DD UNIT=2314,SPACE=(TRK,( 1 ) ) 
DD UNIT=2314,SPACE=(TRK,( 1 ) ) 
DD * 
COPY 0UTDD=IN0UT4 , INDD=IN0UT5 






Before 


After 


copy 
operation 


processing 
DATASET5 



Figure 6. Copying a Partitioned Data Set — Full Copy 



The control statements are discussed below: 

• IN0UT4 DD defines a partitioned data set (DATASET4). This data set is new and is 
to be kept after the copy operation. Five tracks are allocated for the data set on a 
2314 volume. Two blocks are allocated for directory entries. 

• IN0UT5 DD defines a partitioned data set (DATASET5), which resides on a 2314 
volume and contains two members (A and 0). 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2314 
volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2314 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement. 

• COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. The OUTDD parameter 
specifies IN0UT4 as the DD statement for the output data set (DATASET4); the 
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INDD parameter specifies IN0UT5 as the DD statement for the input data set. After 
the copy operation is finished, the output data set (DATASET4) will contain the 
same members that are on the input data set (DATASET5); however, there will be 
no embedded unused space on DATASET4. 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

In this example, members are to be copied from three input partitioned data sets 
(DATASETl, DATASET5, and DATASET6) to an existing output partitioned data set 
(DATASET2). The sequence in which the control statements occur controls the 
manner and sequence in which partitioned data sets are processed. Figure 7 shows 
the input and output data sets before and after processing. 






Output 
DATASET2 



F= 





Before 


After 


After 


After 


copy 
operation 


processing 
DATASETl 


processing 
DATASET6 


processing 
DATASET5 



Figure 7. Copying from Three Input Partitioned Data Sets 
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The example follows: 

//COPY JOB 6 # 9 9 , MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 



//IN0UT1 


.DD 


// 




//IN0UT5 


DD 


// 




//IN0UT2 


DD 


// 




//IN0UT6 


DD 


// 




//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


co; 



lEBCOPY Example 3 



DSNAME=DATASET1 ,UNIT=231 1 ,V0L=SER=1 11112, 
DISP=( OLD, KEEP) 

DSNAME=DATASET5,UNIT=2301 ,V0L=SER=11 1114, 
DISP=0LD 

DSNAME=DATASET2,UNIT=2302,VOL=SER=11 1115, 
DISP=( OLD, KEEP) 

DSNAME=DATASET6,UNIT=2301 ,V0L=SER=1 11117, 
DISP=( OLD, DELETE) 

UNIT=23 1 1 , SPACE=( TRK, ( 1 ) ) 

UNIT=231 1 ,SPACE=(TRK,( 1 ) ) 

* 
COPY 0UTDD=IN0UT2 
INDD=IN0UT1 
INDD=IN0UT6 
rNDD=IN0UT5 
/* 

The control statements are discussed below: 

• INOUTl DD defines a partitioned data set (DATASETl). This data set, which 
resides on a 2311 volume, contains three members (A, B, and F) in fixed format 
with a logical record length of 80 bytes and a block size of 80 bytes. 

• IN0UT5 DD defines a partitioned data set (DATASET5), which resides on a 2301 
volume. This data set contains two members (A and C) in fixed blocked format with 
a logical record length of 80 bytes and a block size of 160 bytes. 

• IN0UT2 DD defines a partitioned data set (DATASET2), which resides on a 2302 
volume. This data set contains two members (C and E) in fixed blocked format. The 
members have a logical record length of 80 bytes and a block size of 240 bytes. 

• IN0UT6 DD defines a partitioned data set (DATASET6), which resides on a 2301 
volume. This data set contains three members (B, C, and D) in fixed blocked format 
with a logical record length of 80 bytes and a block size of 400 bytes. This data set 
is to be deleted when processing is completed. 

o SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement and three INDD statements. 

• COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. The OUTDD parameter 
specifies IN0UT2 as the DD statement for the output data set (DATASET2). 

• The first INDD statement specifies INOUTl as the DD statement for the first input 
data set (DATASETl) to be processed. All members (A, B, and F) are copied to the 
output data set (DATASET2). 

• The second INDD statement specifies IN0UT6 as the DD statement for the second 
input data set (DATASET6) to be processed. Processing occurs, as follows: (1) 
members B and C, which already exist on DATASET2, are not copied to the output 
data set (DATASET2), (2) member D is copied to the output data set (DATASET2), 
and (3) all members on DATASET6 are lost when the data set is deleted. 

• The third INDD statement specifies IN0UT5 as the DD statement for the third input 
data set (DATASET5) to be processed. No members are copied to the output data 
set (DATASET2) because all of them exist on DATASET2. 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

In this example, members are to be copied from an input partitioned data set 
(DATASET6) to an existing output partitioned data set (DATASET2). In addition, all 
copied members are to replace identically named members on the output partitioned 
data set. Figure 8 shows the input and output data sets before and after processing. 
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Figure 8. Copy Operation witli "Replace" Specified on the Data Set Level 



The example follows: 



//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//IN0UT2 


DD 


// 




//IN0UT6 


DD 


// 




//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 


/* 





06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASET2 , UNIT=23 1 4 , VOL=SER= 111113, 
DISP=OLD 

DSNAME=DATASET6,UNIT=2302,VOL=SER=1 11117, 
DISP=( OLD, KEEP) 

UNIT=23 1 1 , SPACE=( TRK, ( 1 ) ) 

UNIT=2311 ,SPACE=(TRK,( 1 ) ) 

* 

0UTDD=IN0UT2 , INDD=( ( IN0UT6 , R ) ) 



The control statements are discussed below: 

• IN0UT2 DD defines a partitioned data set (DATASET2), which resides on a 2314 
volume. This data set contains two members (C and E). 

• IN0UT6 DD defines a partitioned data set (DATASET6), which resides on a 2302 
volume. This data set contains three members (B, C, and D). 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement and an INDD statement. 

• COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. The OUTDD parameter 
specifies IN0UT2 as the DD statement for the output data set (DATASET2). The 
INDD parameter specifies IN0UT6 as the DD statement for the input data set 
(DATASET6). Members B, C, and D are copied to the output data set (DATASET2). 
The pointer in the output data set directory is changed to point to the new (copied) 
member C; thus, the space occupied by the old member C is embedded unused 
space. Member C is copied even though the output data set already contains a 
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member named "C" because the replace option is specified for all identically 
named members on the input data set; that is, the replace option is specified on 
the data set level. 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

In this example, five members (A, C, D, E, and G) are to be selected from two input 
partitioned data sets (DATASET6 and DATASET2) to be copied to a new output 
partitioned data set (DATASET4). Figure 9 shows the input and output data sets 
before and after processing. 





Member D is 
selected first 




Before 

copy 

operation 




Directory 
C D E 



After 

processing 
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Figure 9. Copying Selected Members with Reblocking and Deblocking 



The example follows: 



06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASET2 , UNIT=23 1 4 , V0L=SER=1 11114, 
DISP=( OLD, DELETE) 

DSNAME=DATASET6 , UNIT=2302 , VOL-SER= 111117, 
DISP=( OLD, KEEP) 

DSNAME=DATASET4 , UNIT=23 1 1 , V0L=SER=1 11116, 
DISP=( NEW, KEEP ) , SPACE=( TRK, ( 5 , , 2 ) ) , 
DCB=(RECFM=VB,LRECL=96,BLKSIZE=300 ) 

UNIT=2311 ,SPACE=(TRK,( 1 ) ) 

UNIT=231 1 ,SPACE={TRK,( 1 ) ) 

* 

0UTDD=IN0UT4 
INDD=IN0UT6 
INDD=IN0UT2 



The control statements are discussed below: 

• IN0UT2 DD defines a partitioned data set (DATASET2), which resides on a 2314 
volume. This data set contains two members (C and E) in variable blocked format 
with a logical record length of 96 bytes and a block size of 500 bytes. This data set 
is to be deleted when processing is completed. 



//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//IN0UT2 


DD 


// 




//IN0UT6 


DD 


// 




//IN0UT4 


DD 


// 




// 




//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 


SELECT M 


EMBER 


/* 
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• IN0UT6 DD defines a partitioned data set (DATASET6), which resides on a 2302 
volume. This data set contains three members (B, C, and D) in variable format with 
a logical record length of 96 bytes and a block size of 100 bytes. 

• IN0UT4 DD defines a partitioned data set (DATASET4). This data set is new and is 
to be kept after the copy operation. Five tracks are allocated for the data set on a 
2311 volume. Two blocks are allocated for directory entries. In addition, records 
are to be copied to this data set in variable blocked format with a logical record 
length of 96 bytes and a block size of 300 bytes. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement, two INDD statements, and a SELECT statement. 

• COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD parameter specifies IN0UT4 as the 
DD statement for the output data set (DATASET4). 

• The first INDD statement specifies IN0UT6 as the DD statement for the first input 
data set (DATASET6) to be processed. The members specified on the SELECT 
statement are searched for. The found members (C and D) are copied to the output 
data set (DATASET4) in the order in which they reside on the input data set, that is, 
in TTR order. In this case, member D is copied first, and then member C is copied. 

• The second INDD statement specifies IN0UT2 as the DD statement for the second 
input data set (DATASET2) to be processed. The members specified on the SELECT 
statement and not found on the first input data set are searched for. The found 
member (E) is copied onto the output data set (DATASET4). All members on 
DATASET2 are lost when the data set is deleted. 

• SELECT specifies the members to be selected from the input data sets (DATASET6 
and DATASET2) to be copied to the output data set (DATASET4). 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

lEBCOPY Example 5 In this example, two members (A and B) are to be selected from two input partitioned 

data sets (DATASET5 and DATASET6) to be copied to an existing output partitioned 
data set (DATASETl). Member B is to replace an identically named member that 
already exists on the output data set. Figure 10 shows the input and output data sets 
before and after processing. 

The example follows: 

06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASET1 ,UNIT=231 1 ,V0L=SER=1 11112, 
DISP=( OLD, KEEP) 

DSNAME=DATASET6,UNIT=2302,VOL=SER=1 11115, 
DISP=OLD 

DSNAME=DATASET5 , UNIT=23 1 1 , VOL=SER= 111116, 
DISP=( OLD, KEEP) 

UNIT=231 1 ,SPACE=(TRK, ( 1 ) ) 

UNIT=23 1 1 , SPACE=( TRK, ( 1 ) ) 

* 

0UTDD=IN0UT1 
INDD=IN0UT5 , IN0UT6 
=((E,,R),A) 

The control statements are discussed below: 

• INOUTl DD defines a partitioned data set (DATASETl). This data set resides on a 
2311 volume and contains three members (A, B, and F). 

• INCUTS DD defines a partitioned data set (DATASET6). This data set resides on a 
2302 volume and contains three members (B, C, and D). 

• IN0UT5 DD defines a partitioned data set (DATASET5). This data set resides on a 
2311 volume and contains two members (A and C). 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 
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//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//INOUTl 


DD 


// 


] 


//IN0UT6 


DD 


// 


] 


//IN0UT5 


DD 


// 


] 


//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 


SELECT MEMBER^ 


/* 
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Copy replacing 
member B 



Old member B , 
not pointed at 



Figure 10. Selective Copy with "Replace" Specified on the Member Level 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement, an INDD statement, and a SELECT statement. 

• COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDO parameter specifies INOUTl as the 
DD statement for the output data set (DATASETl). 

• INDD specifies IN0UT5 as the DD statement for the first input data set 
(DATASET5) to be processed and IN0UT6 as the DD statement for the second 
input data set (DATASET6) to be processed. Processing occurs, as follows: (1) 
selected members are searched for on DATASET5, (2) member A is found, but is 
not copied to the output data set because it already exists on DATASET2 and the 
replace option is not specified, (3) selected members not found on DATASET5 are 
searched for on DATASET6, and (4) member B is found and copied to the output 
data set (DATASETl), even though a member named B already exists on the output 
data set, because the replace option is specified for member B on the member 
level. The pointer in the output data set directory is changed to point to the new 
(copied) member B; thus, the space occupied by the old member B is unused. 

• SELECT specifies the members to be selected from the input data sets (DATASET5 
and DATASET6) to be copied to the output data set (DATASETl). 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

In this example, two members (A and B) are to be selected from two input partitioned 
data sets (DATASET5 and DATASET6) to be copied to an existing output partitioned 
data set (DATASETl). All members found on DATASET5 are to replace identically 
named members on DATASETl. Figure 11 shows the input and output data sets 
before and after processing. 
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Figure 11. Selective Copy with "Replace" Specified on the Data Set Level 



The example follows: 



//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//IN0UT1 


DD 


// 




//IN0UT5 


DD 


// 




//IN0UT6 


DD 


// 




//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 


SELECT MEMBER 


/* 





06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASET 1 , UNIT=2 3 1 1 , VOL=SER= 111112, 
DISP=( OLD, KEEP) 

DSNAME=DATASET5 , UNIT=23 1 4 , V0L=SER=1 11114, 
DISP=( OLD, DELETE) 

DSNAME=DATASET6,UNIT=2301 ,V0L=SER=1 11115, 
DISP=( OLD, KEEP) 

UNIT=2311 ,SPACE=(TRK,( 1 ) ) 

UNIT=23 1 1 , SPACE=( TRK, ( 1 ) ) 

* 

0UTDD=IN0UT1 
INDD=( ( IN0UT5 , R ) , IN0UT6 ) 



The control statements are discussed below: 

• INOUTl DD defines a partitioned data set (DATASETl). This data set resides on a 
2311 volume and contains three members (A, B, and F). 

• INPUTS DD defines a partitioned data set (DATASET5). This data set contains two 
members (A and C) and can reside on either a 2314 or 2319 volume. This data set 
is to be deleted when processing is completed. 

• IN0UT5 DD defines a partitioned data set (DATASET6). This data set contains 
three members (B, C, and D) and resides on a 2301 volume. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 
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• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement, an INDD statement, and a SELECT statement. 

• COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD operand specifies INOUTl as the 
DD statement for the output data set (DATASETl). 

• INDD specifies IN0UT5 as the DD statement for the first input data set 
(DATASET5) to be processed and IN0UT6 as the statement for the second input 
data set (DATASET6) to be processed. Processing occurs, as follows: (1) selected 
members are searched for on DATASET5, (2) member A is found and copied to the 
output data set (DATASETl) because the replace option was specified on the data 
set level for DATASET5, (3) member B, which was not found on DATASET5 is 
searched for and found on DATASET6, (4) member B is not copied because 
DATASETl already contains a member called member B and the replace option Is 
not specified for DATASET6. The pointer in the output data set directory is changed 
to point to the new (copied) member A; thus, the space occupied by the old 
member A is unused. 

• SELECT specifies the members to be selected from the input data sets (DATASET5 
and DATASET6) to be copied to the output data set (DATASETl). 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

In this example, four members (A, B, C, and D) are to be selected from an input 
partitioned data set (DATASET6) to be copied to an existing output partitioned data 
set (DATASET3). Member B is to be renamed H; member C is to be renamed J; and 
member D is to be renamed K. In addition, member C (renamed J) is to replace the 
identically named member (J) on the output partitioned data set. Figure 12 shows the 
input and output data sets before and after processing. 

The example follows: 

//COPY JOB #990,MCEWAN 
//JOBSTEP EXEC PGM=IEBCOPY 
//SYSPRINT DD SYSOUT=A 

//IN0UT3 DD DSNAME=DATASET3,UNIT=2311 ,V0L=SER=1 111 14, 
// DISP=( OLD, KEEP) 

//IN0UT6 DD DSNAME=DATASET6,UNIT=231 1 ,V0L=SER=1 11117, 
// DISP=( OLD, DELETE) 

//SYSUT3 DD UNIT=2311 ,SPACE=(TRK,( 1 ) ) 
//SYSUT4 DD UNIT=231 1 ,SPACE=(TRK,( 1 ) ) 
//SYSIN DD * 
COPYOPER COPY 0UTDD=IN0UT3 
INDD=IN0UT6 
SELECT MEMBER=( (B,H), ( C, J,R ) , A, ( D,K ) ) 
/* 

The control statements are discussed below: 

• IN0UT3 DD defines a partitioned data set (DATASET3). This data set contains four 
members (D, G, H, and J). 

• IN0UT6 DD defines a partitioned data set (DATASET6). This data set contains 
three members (B, C, and D) and resides on a 2311 volume. DATASET6 is to be 
deleted when processing is completed; thus, all members on this data set are lost. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 



SYSUT4 DD defines a temporary spil 
volume. 



data set. One track is allocated on a 2311 



SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement, an INDD statement, and a SELECT statement. 

COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD parameter specifies IN0UT3 as the 
DD statement for the output data set (DATASET3). 

INDD specifies IN0UT6 as the DD statement for the input data set (DATASET6). 
Processing occurs, as follows: (1) selected members are searched for on 
DATASET6, (2) member B is found, but is not copied to DATASET3 because its 
intended new name (H) is identical to the name of a member (H), which already 
exists on the output data set, and replace is not specified, (3) member C is found 
and copied to the output data set (DATASET3), although its new name (J) is 
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Figure 12. Renaming Selected Members Using lEBCOPY 



identical to the name of a member (J), which already exists on the output data set, 
because the replace option is specified for the renamed member, and (4) member 
D is copied onto the output data set (DATASET3) because its new name (K) does 
not already exist there. 

• SELECT specifies the members to be selected from the input data set (DATASET6) 
to be copied to the output data set (DATASET3). 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

In this example, five members (A, B, C, J, and L) are to be excluded from the copy 
operation when each of the input partitioned data sets (DATASETl, DATASET3, and 
DATASET6) is processed. In addition, replace is specified for the last input partitioned 
data set (DATASET6) to be processed; thus, with the exception of the members 
specified on the EXCLUDE statement, all members on DATASET6 will replace any 
identically named members on the output partitioned data set (DATASET4). Figure 13 
shows the input and output data sets before and after processing. 

The example follows: 

06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASET1 ,UNIT=2314, V0L=SER=1 11112, 
DISP=( OLD, KEEP) 

DSNAME=DATASET3 , UNIT=2 314, VOL=SER= 111114, 
DISP=OLD 

DSNAME=DATASET4,UNIT=2314,VOL=SER=1 11115, 
DISP=( NEW, KEEP ) , SPACE=( TRK, (5,1,2)), 
DCB=(LRECL=100,RECFM=FB,BLKSIZE=400) 

DSNAME=DATASET6 , UNIT=23 1 4 , VOL=SER= 111116, 
DISP=OLD 

UNIT=2314,SPACE=(TRK,( 1 ) ) 

UNIT=23 1 4 , SPACE=( TRK, ( 1 ) ) 

* 

COPYOPER COPY 0UTDD=IN0UT4 , INDD=INOUT 1 , IN0UT3 , ( IN0UT6 , R ) 

EXCLUDE MEMBER=A,J,B,L,C 
/* 



//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//IN0UT1 


DD 


// 




//IN0UT3 


DD 


// 




//IN0UT4 


DD 


// 




// 




//IN0UT6 


DD 


// 




//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSIN 


DD 
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Figure 13. Exclusive Copy witli "Replace" Specified for One Input Partitioned Data Set 

The control statements are discussed below: 

• INOUTl DD defines a partitioned data set (DATASETl). This data set contains 
three members (A, B, and F) and resides on a 2314 volume. The record format is 
fixed blocl<ed with a logical record length of 100 bytes and a block size of 400 
bytes. 

• IN0UT3 DD defines a partitioned data set (DATASET3), which resides on a 2314 
volume. This data set contains four members (D, G, H, and J) in fixed blocked 
format with a logical record length of 100 bytes and a block size of 600 bytes. 

• IN0UT4 DD defines a new partitioned data set (DATASET4). Five tracks are 
allocated for the copied members on a 2314 volume. Two blocks are allocated for 
directory entries. In addition records are to be copied to this data set in fixed 
blocked format with a logical record length of 100 bytes and a block size of 400 
bytes. 

• IN0UT6 DD defines a partitioned data set (DATASET6). This data set contains 
three members (B, C, and D) in fixed format. The records have a logical record 
length of 100 bytes and a block size of 100 bytes. This data set resides on a 2314 
volume. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2314 
volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2314 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement and an EXCLUDE statement. 

• COPY indicates the start of the copy operation. The presence of an EXCLUDE 
statement causes an exclusive copy. The OUTDO parameter specifies IN0UT4 as 
the DD statement for the output data set (DATASET4). The INDD parameter 
specifies INOUTl as the DD statement for the first input data set (DATASETl) to 
be processed, IN0UT3 as the DD statement for the second input data set 
(DATASET3) to be processed, and IN0UT6 as the DD statement for the last input 
data set (DATASET6) to be processed. Processing occurs, as follows: (1) member 
F, which is not named on the EXCLUDE statement, is copied from DATASETl, (2) 
members D, G, and H, which are not named on the EXCLUDE statement, are copied 
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from DATASET3, and (3) member D is copied from DATASET6 because the replace 
option is specified for nonexcluded members. The pointer in the output data set 
directory is changed to point at the new (copied) member D; thus, the space 
occupied by the old member D (copied from DATASET3) is unused. 

• EXCLUDE specifies the members to be excluded from the copy operation. The 
named members are excluded from all of the input partitioned data sets specified 
in the copy operation. 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore. It is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

In this example, a partitioned data set (DATASET5) is to be compressed in place. 
Figure 14 shows the input and output data sets before and after processing. 

The example follows: 

//COPY JOB 
//JOBSTEP EXEC 
//SYSPRINT DD 
//IN0UT5 DD 

// 

//SYSUT3 DD 

//SYSUT4 DD 

//SYSIN DD 

COPYOPER COPY 

/* 



06#990,MCEWAN 
PGM=IEBCOPY 
SYSOUT=A 

DSNAME=DATASET5,UNIT=2314,VOL=SER=1 11113, 
DISP=( OLD, KEEP) 

UNIT=23 1 1 , SPACE=( TRK, ( 1 ) ) 
UNIT=2311 ,SPACE=(TRK,( 1 ) ) 
* 

0UTDD=IN0UT5 , INDD=IN0UT5 





Member C 
Unused 



Before 
copy 




Figure 14. Compressing a Data Set in Place 



The control statements are discussed below: 

• IN0UT5 DD defines a partitioned data set (DATASET5). This data set contains two 
members (A and C) and can reside on either a 2314 or 2319 volume. 

• SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 
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• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement. 

• COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy; however, the same DD 
statement is specified for both the INDD and OUTDO parameters, causing a 
compress in place of the specified data set. The OUTDD parameter specifies 
IN0UT5 as the DD statement for the output data set (DATASET5). The INDD 
parameter also specifies IN0UT5 as the DD statement for the input data set 
(DATASET5). 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

In this example, two input partitioned data sets (DATASET5 and DATASET6) are to be 
copied to an existing output partitioned data set (DATASETl). In addition, all members 
on DATASET6 are to be copied; members on the output data set that have the same 
names as the copied members are replaced. After DATASET6 is processed, the output 
data set (DATASETl) is to be compressed in place. Figure 15 shows the input and 
output data sets before and after processing. 
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Figure 15. Compress-in-Place Following Full Copy with "Replace" Specified 



74 Utilities (Release 21.7) 



//COPY 


JOB 


//JOBSTEP 


EXEC 


//SYSPRINT 


DD 


//IN0UT1 


DD 


// 




//IN0UT5 


DD 


// 




//IN0UT6 


DD 


// 




//SYSUT3 


DD 


//SYSUTA 


DD 


//SYSIN 


DD 


COPYOPER 


COPY 



The example follows: 

06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASET1 , UNIT=231 4 , V0L=SER=1 11112, 
DISP=( OLD, KEEP) 

DSNAME=DATASET5,UNIT=231 1 ,V0L=SER=1 11114, 
DISP=OLD 

DSNAME=DATASET6,UNIT=231 1 ,V0L=SER=1 11115, 
DISP=( OLD, KEEP) 

UNIT=231 1 ,SPACE=(TRK,( 1 ) ) 

UNIT=2311 ,SPACE=(TRK,( 1 ) ) 

* 

0UTDD=IN0UT1 
INDD=IN0UT5 , ( IN0UT6 , R ) , INOUT 1 
/* 

The control statements are discussed below: 

INOUTl DD defines a partitioned data set (DATASETl). This data set contains 
three members (A, B, and F) and resides on a 2314 or 2319 volume. 

IN0UT5 DD defines a partitioned data set (DATASET5). This data set contains two 
members (A and C) and resides on a 2311 volume. 

IN0UT6 DD defines a partitioned data set (DATASET6). This data set contains 
three members (B, C, and D) and resides on a 2311 volume. 

SYSUT3 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains a COPY statement and an INDD statement. 

COPY indicates the start of the copy operation. The OUTDD operand specifies 
INOUTl as the DD statement for the output data set (DATASETl). The absence of 
a SELECT or EXCLUDE statement causes a default to a full copy. 

INDD specifies IN0UT5 as the DD statement for the first input data set 
(DATASET5) to be processed. It then specifies IN0UT6 as the DD statement for the 
second input data set (DATASET6) to be processed; in addition, the replace option 
is specified for all members copied from DATASET6. Finally, it specifies INOUTl as 
the DD statement for the last input data set (DATASETl) to be processed; this 
causes a compress in place of DATASETl because it is also specified as the output 
data set. Processing occurs, as follows: (1) member A is not copied from 
DATASET5 onto the output data set (DATASETl) because it already exists on 
DATASETl and the replace option was not specified for DATASET5, (2) member C 
is copied from DATASET5 to the output data set (DATASETl), occupying the first 
available space, and (3) all members are copied from DATASET6 to the output data 
set (DATASETl), immediately following the last member. Members B and C are 
copied even though the output data set already contains members with the same 
names because the replace option is specified on the data set level. The pointers in 
the output data set directory are changed to point to the new members B and C; 
thus, the space occupied by the old members B and C is unused. The members 
currently on DATASETl are compressed in place, thereby eliminating embedded 
unused space. 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 
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In this example, members are to be selected, excluded, and copied from input 
partitioned data sets onto an output partitioned data set. This example is designed to 
illustrate multiple copy operations. Figure 16 shows the input and output data sets 
before and after processing. 

The example follows: 



//COPY JOB 
//JOBSTEP EXEC 
//SYSPRINT DD 
//INOUTA DD 

// 

//INOUTB DD 

// 

//INOUTC DD 

// 

//INOUTD DD 

// 

//INOUTE DD 

// 

//INOUTX DD 

// 

//SYSUT3 DD 

//SYSUT4 DD 

//SYSIN DD 

COPERS T1 COPY 
COPY 



06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT=A 

DSNAME=DATASETA,UNIT=2314,VOL=SER=11 1113, 
DISP=OLD 

DSNAME=DATASETB,UNIT=2314,VOL=SER=11 1115, 
DISP=( OLD, KEEP) 

DSNAME=DATASETC , UNIT=2 314, VOL=SER= 111114, 
DISP=( OLD, KEEP) 

DSNAME=DATASETD,UNIT=2314,VOL=SER=-11 1116, 
DISP=OLD 

DSNAME=DATASETE,UNIT=2314,VOL=SER=11 1117, 
DISP=OLD 

DSNAME=DATASETX , UNIT=2 3 1 4 , VOL=SER= 111112, 
DISP=( NEW, KEEP ),SPACE=(TRK,( 5,1,2)) 

UNIT=23 1 4 , SPACE=( TRK, ( 1 ) ) 

UNIT=2314,SPACE=(TRK,( 1 ) ) 

* 

0=INOUTX, I=INOUTA 



OUTDD=INOUTA , INDD=INOUTA 
INDD=INOUTB 
COPY 0=INOUTA 

INDD=INOUTD 
EXCLUDE MEMBER=MM 

INDD=INOUTC 
SELECT MEMBER ( ( ML , MD , R ) ) 
INDD=INOUTE 
/* 
The control statements are discussed below: 

INOUTA DD defines a partitioned data (DATASETA). This data set contains eight 
members (MA, MB, MC, MD, ME, MF, MG, and MH) and resides on either a 2314 or 
a 2319 volume. 

INOUTB DD defines a partitioned data set (DATASETB). This data set resides on 
either a 2314 or a 2319 volume and contains two members (MA and MJ). 

INOUTC DD defines a partitioned data set (DATASETC), which resides on either a 
2314 or a 2319 volume. The data set contains four members (MF, ML, MM, and 
MN). 

INOUTD DD defines a partitioned data set (DATASETD). This data set resides on 
either a 2314 or a 2319 volume and contains two members (MM and MP). 

INOUTE DD defines a partitioned data set (DATASETE). This data set contains four 
members (MD, ME, MF, and MT) and resides on either a 2314 or a 2319 volume. 

INOUTX DD defines a partitioned data set (DATASETX). This data set is new and is 
to be kept after the copy operation. Five tracks are allocated for the data set on 
either a 2314 or a 2319 volume. Two blocks are allocated for directory entries. 

SYSUT3 DD defines a temporary spill data set. One track is allocated on either a 
2314 or a 2319 volume. 

SYSUT4 DD defines a temporary spill data set. One track is allocated on either a 
2314 or a 2319 volume. 

SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains two COPY statements, several INDD statements, a SELECT statement 
and an EXCLUDE statement. 

The first COPY statement indicates the start of the first copy operation. This copy 
operation is done to create a back-up copy of DATASETA, which is subsequently 
compressed in place. 
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Figure 16. Multiple Copy Operations/Copy Steps 



lEBCOPY Example 12 



• The second COPY statement indicates the start of another copy operation. The 
absence of a SELECT or EXCLUDE statement causes a default to a full copy; 
however, the same DD statement, INOUTA, is specified for both the INDD and 
OUTDD parameters, causing a compress in place of the specified data set. 

• INDD specifies INOUTB as the DD statement for the input data set (DATASETB) to 
be copied. Only member MJ is copied because member MA already exists on the 
output data set. 

• The third COPY statement indicates the start of the third copy operation. The 
OUTDD parameter specifes INOUTA as the DD statement for the output data set 
(DATASETA). This copy operation contains more than one copy step. 

• The first INDD statement specifies INOUTD as the DD statement for the first input 
data set (DATASETD) to be processed. Only member MP is copied to the output 
data set (DATASETA) because member MM is specified on the EXCLUDE 
statement. 

• EXCLUDE specifies the member to be excluded from the first copy step within this 
copy operation. 

• The second INDD statement marks the beginning of the second copy step for this 
copy operation and specifies INOUTC as the DD statement for the second input 
data set (DATASETC) to be processed. Member ML is searched for, found, and 
copied to the output data set (DATASETA). Member ML is copied even though its 
new name (MD) is identical to the name of a member (MD) that already exists on 
the output data set, because the replace option is specified for the renamed 
member. 

• SELECT specifies the member to be selected from the input data set (DATASETC) 
to be copied to the output partitioned data set. 

• The third INDD statement marks the beginning of the third copy step for this copy 
operation and specifies INOUTE as the DD statement for the last data set 
(DATASETE) to be copied. Only member MT is copied because the other members 
already exist on the output data set. Because the INDD statement is not followed 
by an EXCLUDE or SELECT statement, a full copy is performed. 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

The output data set is compressed in place first to save space because it is known 
that it contains embedded unused space. 

In this example, members are to be selected, excluded, and copied from input 
partitioned data sets to an output partitioned data set. This example is designed to 
illustrate multiple copy operaticjns. Figure 17 shows the input and output data sets 
before and after processing. 

The example follows: 



//COPY JOB 
//JOBSTEP EXEC 
//SYSPRINT DD 
//INOUTA DD 

// 

//INOUTB DD 

// 

//INOUTC DD 

// 

//INOUTD DD 

// 

//INOUTE DD 

// 

//SYSUT3 
//SYSUT4 
//SYSIN 
COPY 



06#990,MCEWAN 

PGM=IEBCOPY 

SYSOUT-A 

DSNAME=DATASETA,UNIT=231 1 ,V0L=SER=1 11113, 
DISP=OLD 

DSNAME=DATASETB , VOL=SER= 111115, 
DISP=( OLD, KEEP ),UNIT=231 1 

DSNAME=DATASETC,V0L=SER=1 11114, 
DISP=( OLD, KEEP ),UNIT=231 1 

DSNAME=DATASETD,V0L=SER=1 11116, 
DISP=OLD,UNIT=231 1 

DSNAME=DATASETE , VOL=SER= 111117, 
DISP=OLD,UNIT=231 1 

UNIT=231 1 ,SPACE=(TRK,( 1 ) ) 

UNIT=231 1 ,SPACE=(TRK,( 1 ) ) 



DD 
DD 

DD * 
OUTDD=INOUTA 

INDD=INOUTE 
SELECT MEMBER=MA,MJ 

INDD=INOUTC 
EXCLUDE MEMBER=MM,MN 
COPY 0=INOUTB,INDD=INOUTD 

I=( ( INOUTC , R ) , INOUTB ) 
COPY 0=INOUTD,I=( (INOUTB, R )) 
SELECT MEMBER=MM 
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First copy operation 



Second copy operation 




Figure 17. Multiple Copy Operations/Copy Steps Within a Job Step 






The control statements are discussed below: 

• INOUTA DD defines a partitioned data set (DATASETA). This data set contains 
three members (MA, MB, and MD) and resides on a 2311 volume. 

• INOUTB DD defines a partitioned data set (DATASETB). This data set resides on a 
2311 volume and contains two members (MA and MJ). 

• INOUTC DD defines a partitioned data set (DATASETC), which resides on a 2311 
volume. This data set contains four members (MF, ML, MM, and MN). 

• INOUTD DD defines a partitioned data set (DATASETD). This data set resides on a 
2311 volume and contains two members (MM and MP). 

• INOUTE DD defines a partitioned data set (DATASETE), which resides on a 2311 
volume. This data set contains three members (MA, MJ and MK). 

• SYSUT3 DD defines a temporary spill data set. One track Is allocated on a 2311 
volume. 

• SYSUT4 DD defines a temporary spill data set. One track is allocated on a 2311 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. The data 
set contains three COPY statements, SELECT and EXCLUDE statements, and 
several INDD statements. 

• The first COPY statement indicates the start of a copy operation. The OUTDD 
operand specifies INOUTA as the DD statement for the output data set 
(DATASETA). 

• The first INDD statement specifies INOUTE as the DD statement for the first input 
data set (DATASETE) to be processed. Processing occurs, as follows: (1) member 
MA is searched for and found, but is not copied because the replace option is not 
specified, and (2) member MJ is searched for, found, and copied to the output data 
set. Members are not searched for again after they are found. 

• SELECT specifies the members (MA and MJ) to be selected from the input data set 
(DATASETE) to be copied. 

• The second INDD statement marks the end of the first copy step and the beginning 
of the second copy step within the first copy operation. It specifies INOUTC as the 
DD statement for the second input data set (DATASETC) to be processed. 
Members MF and ML, which are not named on the EXCLUDE statement, are copied 
because neither exists on the output data set. 

• EXCLUDE specifies the members (MM and MN) to be excluded from the second 
copy operation. 

• The second COPY statement indicates the start of another copy operation. The 
absence of a SELECT or EXCLUDE statement causes a default to a full copy. The 
(OUTDD) parameter specifies INOUTB as the output data set (DATASETB). The 
INDD parameter specifies INOUTD as the first input data set (DATASETD) to be 
processed. Members MP and MM are copied to the output data set. 

• INDD(I) specifies INOUTC as the DD statement for the second input data set 
(DATASETC) and INOUTB as the DD statement for the third input data set 
(DATASETB) to be processed. Members MF, ML, MM, and MN are copied from 
DATASETC. Member MM is copied, although it already exists on the output 
partitioned data sets, because the replace option is specified. Because DATASETB 
is also the data set specified in the OUTDD PARAMETER, a compress in place takes 
place. (The pointer in the output set directory is changed to point to the new 
(copied) member MM; thus the space occupied by the replaced member MM is 
embedded unused space.) 

• The third COPY statement indicates the start of another copy operation. The 
(OUTDD) parameter specifies INOUTD as the DD statement for the output data set 
(DATASETD). The I (INDD) parameter specifies INOUTB as the DD statement for 
the input data set (DATASETB). 

• SELECT specifies the member (MM) to be selected from the input partitioned data 
set (DATASETB) to.be copied. The replace option is specified on the data set level. 

The temporary spill data sets may or may not be opened, depending on the amount of 
main storage available; therefore, it is suggested that the SYSUT3 and SYSUT4 DD 
statements always appear in the job stream. 

Data sets used as input data sets in one copy operation can be used as output data 
sets in another copy operation, and vice versa. 
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lEBDG Program 



IBM-Supplied Patterns 



lEBDG is a data set utility used to provide a pattern of test data to be used as a 
programming debugging aid. (See "Introduction" for general data set utility 
information.) 

An output data set, containing records of any format, can be created through the use 
of utility control statements, with or without input data. An optional user exit is 
provided to pass control to a user routine to monitor each output record before it is 
written. Sequential, indexed sequential, and partitioned data sets can be used for 
input or output. 

To generate test data, the user constructs a pattern of data that he can analyze 
quickly for predictable results. Test data is generated through the use of utility control 
statements. 

When the user defines the contents of a field, he decides: 

• What type of pattern — IBM-supplied or user-supplied — he wishes to place initially 
in the defined field. 

• What action, if any, is to be performed to alter the contents of the field after it is 
selected for each output record. 

IBM supplies seven patterns: alphameric, alphabetic, zoned decimal, packed decimal, 
binary number, collating sequence, and random number. The user may choose one of 
them when he defines the contents of a field. All patterns except the binary and 
random number patterns repeat in a given field, provided that the defined field length 
is sufficient to permit repetition. For example, the alphabetic pattern is: 

ABCDEFGHIJKLMNOPQRSTUVWXYZ ABCDEFG. . . 

Table 14 shows the IBM-supplied patterns. 



Table 14. IBM- 


■Supplied Patterns 








Type 


Expressed in 
Hexadecimal 




Expressed in 
Printable Characters 




Alphameric 


CI C2 . . .E9 FO. . 


.F9 


ABC ... Z ... 9 




Alphabetic 


CI C2 . . . E9 




ABC ... Z 




Zoned Decimal 


FOFO . . . FOFl 




00 ... 01 




Packed Decimal 


0000 . . . OOIC 
(Positive pattern) 
0000 . . . OOID 
(Negative pattern) 




Not applicable 




Binary Number 


00 ... 01 
(Positive pattern) 
FF . . . FF 
(Negative pattern) 




Not applicable 




Collating Sequence 40 . . . F9 




bc.<(+| &!$*);-,-/.% 
A. . .ZO. . .9 


_>?:#@' = " 


Random Number 


Random hexadecimal digits 


Not applicable 





Note: A packed decimal or binary number is right aligned in the defined field. 

The user can specify a starting character when defining an alphameric, alphabetic, or 
collating sequence field. For example, a ten-byte alphabetic field for which "H" is 
specified as the starting character would appear as: 

HIJKLMNOPQ 

The same ten-byte alphabetic field with no specified starting character would appear 
as: 

ABCDEFGHIJ 

The user can specify a mathematical sign when defining a packed decimal or binary 
field. If no sign is specified, the field is assumed to be positive. 
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User-Specified Pictures 



IVIodification of 
Selected Fields 



Instead of selecting an IBIVI-supplied pattern, the user can specify a picture to be 
placed in the defined field. The user can provide: 

• An EBCDIC character string. 

• A decimal number to be converted to packed decimal by lEBDG. 

• A decimal number to be converted to binary by lEBDG. 

When the user supplies a picture, he must specify a picture length that is equal to or 
less than the specified field length. An EBCDIC picture is left aligned in a defined field; 
a decimal number that is converted to packed decimal or to binary is right aligned in a 
defined field. 

The user can initially load (fill) a defined field with either an EBCDIC character or a 
hexadecimal digit. For example, the 10-byte picture "BADCFEHGJI" is to be placed in 
a 15-byte field. An EBCDIC "2" is to be used to pad the field. The result is 
BADCFEHGJI22222, (If no fill character is provided, the remaining bytes contain 
binary zeros.) Remember that the fill character, if specified, is written in each byte of 
the defined field prior to the inclusion of an IBM-supplied pattern or user-supplied 
picture. 

lEBDG can be used to change the contents of a field in a specified manner. One 
of eight actions can be selected to change a field after its inclusion in each applicable 
output record. These actions are ripple, shift left, shift right, truncate left, truncate 
right, fixed, roll, and wave. 

Figure 18 shows the effects of each of the actions on a six-byte alphabetic field. Note 
that the roll and wave actions are applicable only when a user pattern is supplied. In 
addition, the result of a ripple action depends on which type of pattern — IBM-supplied 
or user-supplied — is present. 
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Figure 18. lEBDG Actions 
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If no action is selected, or if the specified action is not compatible with the format, the 
fixed action is assumed by lEBDG. 

lEBDG uses the following input: 

• An input data set, which contains records that are to be used in the construction of 
an output data set or partitioned data set member. The input data sets are 
optional; that is, output records can be created entirely from utility control 
statements. 

• A control data set, which contains any number of sets of utility control statements. 
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Control 



Job Control Statements 



lEBDG produces the following output: 

• An output data set, which is the result of the lEBDG operation. One output data set 
is created by each set of utility control statements included in the job step. 

• A message data set, which contains informational messages, the contents of 
applicable utility control statements, and any error messages. 

Note that input and output data sets may be sequential, indexed sequential, or 
partitioned data set members. 

BDAM is not supported. 

lEBDG produces a return code to indicate the results of program execution. The return 
codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a user routine returned a code of 16 to lEBDG. The job 
step is terminated at the user's request. 

• 08, which indicates that an error occurred while processing a set of utility control 
statements. No data is generated following the error. Processing continues 
normally with the next set of utility control statements, if any. 

• 12, which indicates that an error occurred while processing an input or output data 
set. The job step is terminated. 

• 16, which indicates that an error occurred from which recovery is not possible. The 
job step is terminated. 

lEBDG is controlled by job control statements and utility control statements. The job 
control statements are used to execute or invoke lEBDG and define the data sets used 
and produced by lEBDG. Utility control statements are used to control the functions of 
the program and to define the contents of the output records. 

Table 15 shows the job control statements necessary for using lEBDG. 

Table 15. lEBDG Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = lEBDG) or, if the job control statements 

reside in a procedure library, the procedure name. Additional information can be 
specified in the EXEC statement; see "PARM Information on the EXEC Statement" 
below. 

SYSPRINT DD Defines a sequential message data set. The data set can be written on a system 
output device, a tape volume, or a direct access volume. 

SYSIN DD Defines the control data set, which contains the utility control statements and, 

optionally, input records. The data set normally resides in the input stream; 
however, it can be defined as a sequential data set or as a member of a 
partitioned data set. 

seqinset DD Defines an optional sequential or indexed sequential data set used as input to 
lEBDG. The data set can reside on a tape volume or on a direct access volume. 
Any number of these statements (each having a ddname different from all other 
ddnames in the job step) can be included in the job step. Each DD statement is 
subsequently referred to by a DSD utility control statement. 

parinset DD Defines an optional input partitioned data set member residing on a direct access 
volume. Any number of these statements (each having a ddname different from 
all other ddnames in the job step) can be included in the job step. The "parinset" 
DD statement is referred to by a DSD utility control statement. 

seqout DD Defines an output (test) sequential or indexed sequential data set. Any number of 

"seqout" DD statements can be included per job step; however, only one 
"seqout" statement is applicable per set of utility control statements. 

parout DD Defines an optional output partitioned data set member to be created and placed 

on a direct access volume. Any number of "parout" DD statements (eachDD 
statement referring to the same or to a different data set) can be included per job 
step; however, only one "parout" statement is applicable per set of utility control 
statements. 
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Restrictions 



FARM Information on 
the EXEC Statement 



The minimum region size required for using lEBDG varies with its use; see OS Storage 
Estimates, GC28-655i, for information on calculating the region size required for a 
particular application. 

The SYSPRINT data set and the SYSIN data set can have any blocking factor. 

Both input and output data sets can contain fixed, variable, or undefined records. 

Refer to OS Data Management Services Guide, GC26-3746, for information on 
estimating space allocations. 

The "seqinset" DD statement can be entered: 

//seqinset DD DSNAME = setname.UNIT = xxxx.DISP = (OLD.KEEP), 
// VOLUME = SER= xxxxxx, LABEL = (...,...), 

// DCB(applicable subparameters) 

The LABEL parameter is included only for a magnetic tape volume. If the input data 
set has an indexed sequential organization, DSORG = IS should be coded in the DCB 
parameter. 

The "parinset" DD statement can be entered: 

//parinset DD DSNAME = setname(membername),UNIT = xxxx.DISP = (OLD, 
// KEEP),VOLUME = SER = xxxxxx, 

// DCB = (applicable subparameters) 

The "seqout" DD statement can be entered: 

//seqout DD DSNAME = setname, UNIT = xxxx, 

// DISP = (,KEEP),VOLUME = SER = xxxxxx, 

// DCB = (applicable subparameters) 

The LABEL parameter is included for magnetic tape; the SPACE parameter is included 
for direct access. 

The "parout" DD statement can be entered: 

//parout DD DSNAME = setname(membername),UNIT = xxxx, 

// VOLUME = SER = xxxxxx,DCB = (applicable 

// subparameters),DISP = (,KEEP), 

// SPACE = (applicable subparameter) 

The SPACE parameter is included on the parout DD statement when creating the first 
member to be placed in a partitioned data set. 

• The input data set record type must agree with the output data set record type. 

• The DSORG subparameter must be included in the DCB subparameters if the input 
or output data set has an indexed sequential organization (DSORG = IS). If 
members of a partitioned data set are used, DSORG = PS or DSORG = PC may be 
coded. If the DSORG subparameter is not coded, DSORG = PS is assumed. 

• If the SYSPRINT DD statement is omitted, no messages are written. 

• On an MVT system, the ddname of the "seqout" DD statement should not be 
SYSPRINT. 

• For an indexed sequential data set, the key length must be specified in the DCB. 

The EXEC statement can include ah optional PARM parameter to specify the number 
of lines to be printed between headings in the message data set, coded as follows: 

PARM = LINECNT=nnnn 

The nnnn is a four-digit decimal number that specifies the number of lines (0000 to 
9999) to be printed per page of output listing. 

If PARM is omitted, 58 lines are printed between headings (unless a channel 12 punch 
is encountered in the carriage control tape, in which case a skip to channel 1 is 
performed and a heading is printed). 

Note: If lEBDG is invoked, the line-count option can be passed in a parameter list that 
is referred to by a subparameter of the LINK or ATTACH macro instruction. In 
addition, a page count can be passed in a six-byte parameter list that is referred to by 
a suparameter of the LINK or ATTACH macro instruction. For a discussion of linkage 
conventions, refer to "Appendix B: Invoking Utility Programs from a Problem 
Program." 
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utility Control Statements 



DSD Statement 



FD Statement 



lEBDG is controlled by the following utility control statements: 

• DSD statement, which specifies the ddnames of the input and output data sets. One 
DSD statement must be included for each set of utility control statements. 

• FD statement, which defines the contents and lengths of fields to be used in 
creating output records. 

• CREATE statement, which defines the contents of output records. 

• REPEAT statement, which specifies the number of times a CREATE statement or a 
group of CREATE statements are to be used in generating output records. 

• END statement, which marks the end of a set of lEBDG utility control statements. 

Any number of sets of control statements can appear in a single job step. Each set 
defines one data set. 

The DSD statement marks the beginning of a set of utility control statements and 
specifies the data sets that lEBDG is to use as input. The DSD statement can be used 
to specify one output data set and any number of input data sets for each application 
of lEBDG. 

The format of the DSD statement is: 

where: 

OUTPUT = (ddname) 

specifies the ddname of the DD statement defining the output data set. 

INPUT = {ddname,...) 

specifies the ddname of a DD statement defining a data set used as input to the 
program. Any number of data sets can be included as input — that is, any number of 
ddnames referring to corresponding DD statements can be coded. Whenever 
ddnames are included on a continuation card, they must begin in column four. 

Note: The ddname SYSIN must not be coded in the INPUT parameter. Each parameter 
should appear no more than once on any DSD statement. 

The FD statement defines the contents and length of a field that will be used 
subsequently by a CREATE statement (or statements) to form output records. A 
defined field within the input logical record may be selected for use in the output 
records if it is referred to, by name, by a subsequent CREATE statement. 

Figure 19 shows how fields defined in FD statements are placed in buffer areas so that 
subsequent CREATE statements can assign selected fields to specific output records. 

FD Statements-define fields 




Contents are placed in buffers S' 
so that subsequent CREATE c' IH i 

statements can selectively ' rieid 1 

create output records. 
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CREATE Statement-creates output record from selected fields 
/ ' 



Output record 



Field 1 



Field 4 



Figure 19. Defining and Selecting Fields for Output Records Using lEBDG 
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Figure 20 shows how the FD statement is used to specify a field in an input record to 
be used in output records. The left-hand side of the figure shows that a field in the 
input record beginning at byte 50 is selected for use in the output record. The 
right-hand side of the figure shows that the field is to be placed at byte 20 in the 
output record. 



Input record 
1 



50 



10 80 



Output record " 
1 20 



40 



80 



LENGTH 

Same as input field 

Figure 20. Field Selected from the Input Record for Use In the Output Record 
The format of the FD statement is: 

[ .LENGTH = /ength-m-faytes ! 

[,STARTLOC = start/ng-byte-/ocat«on] I 

I [,FILL= {'character' }] 1 

I {X'2-hexaclecimal-digits'} j 

i [.FORMAT = pa«ern[„CHARACTER = character]] j 

I [.PICTURE = /ength,{'character-stnng' } j 

! { P*c/ec/ma/-numfaer* } | 

{^'decimal- number' }] | 

j [.SIGN = s/gn] \ 

I [.ACTION = actior)] 

j [.INDEX = numbef[,CYCLE = number][,RANGE = r)umberj] \ 

I [.INPUT = ddname] 

j [.FROMLOC = number] _ 

where: " 

NAME = name 

specifies the name of the field defined by this FD statement. 

LENGTH = length-in-bytes 

specifies the length in bytes of the defined field. For- variable records, four bytes of 
length descriptor are added. 

STARTLOC = starting-byte-location 

specifies a starting location (within all output records using this field) in which a 
field is to begin. For example, if the first byte of an output record is chosen as the 
starting location, the keyword is coded STARTLOC = 1; if the tenth byte is chosen. 
STARTLOC = 10 is coded, etc. If STARTLOC is omitted, the field will begin in the 
first available byte of the output record (determined by the order of specified field 
names in the applicable CREATE statement). For variable records the starting 
location is the first byte after the length descriptor. 

FILL = 

specifies an EBCDIC character or hexadecimal digits to be placed in each byte of 
the defined field prior to any other operation in the construction of a field. If FILL is 
omitted, binary zeros are placed in the field. These values can be coded: 

'character' 

specifies an EBCDIC character to be placed in the defined field. 

X' 2 -hexadecimal -digits' 

specifies two hexadecimal digits (for example. FILL = X'40' or FILL = X'FF') to 
be placed in each byte of the defined field. 

FORMAT = 

specifies an IBM-supplied pattern that is to be placed in the defined field. FORMAT 
must not be used when PICTURE is used. The values that can be coded are: 

pattern 

specifies the IBM-supplied patterns, as follows: 



AN 



specifies an alphameric pattern. 



ZD 



specifies a zoned decimal pattern. 
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PD 

specifies a packed decimal pattern. 

CO 

specifies a collating-sequence pattern. 

Bl 

specifies a binary pattern. 

AL 

specifies an alphabetic pattern. 

RA 

specifies a random binary pattern. 

CHARACTER = character 

specifies the starting character of a field. If CHARACTER is omitted, the starting 
character is as described under "IBM-Supplied Patterns" earlier. 

PICTURE = 

specifies the length and contents of a user-supplied field picture. PICTURE must 
not be used when FORMAT is used. These values can be coded: 

length 

specifies the number of characters in the FD picture. 

'character-string' 

specifies an EBCDIC character string that is to be placed in the defined field. 
The character string is left aligned in the field. A character string may be broken 
in column 71 and must be continued in column 4. Double quotation marks must 
not be coded to represent a single quotation mark within a character string.) 

P'decimal-nunnber' 

specifies a decimal number that is to be converted to packed decimal and 
placed right aligned in the defined field. 

B 'decimal -nunnber' 

specifies a decimal number that is to be converted to binary and placed right 
aligned in the defined field. In all cases, the number of characters within the 
quotation marks must equal the number specified in the length subparameter. 

SIGN = sign 

specifies a mathematical sign (+ or -), which is used when defining a 
packed decimal or binary field. If SIGN is omitted, the sign is assumed to be 
positive. 

ACTION = action 

specifies that the contents of a defined field are to be altered after the field's 
inclusion in an output record. These values can be coded: 

SL 

specifies that the contents of a defined field are to be shifted left after the 
field's inclusion in an output record. 

SR 

specifies that the contents of a defined field are to be shifted right after the 
field's inclusion in an output record. 

TL 

specifies that the contents of a defined field are to be truncated left after the 
field's inclusion in an output record. 

TR 

specifies that the contents of a defined field are to be truncated right after the 
field's inclusion in an output record. 

RO 

specifies that the contents of a defined field are to be rolled after the field's 
inclusion in an output record. RO can be specified only for a user-defined field. 

WV 

specifies that the contents of a defined field are to be waved after the field's 
inclusion in an output record. WV can be specified only for a user-defined field. 

FX 

specifies that the contents of a defined field are to be fixed after the field's 
inclusion in an output record. If ACTION is omitted, FX is assumed. 
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RP 

specifies that the contents of a defined field are to be rippled after the field's 
inclusion in an output record. 

INDEX = number 

specifies a number to be added to this field whenever a specified number of 
records have been written. If INDEX is omitted, no indexing is performed. These 
additional values can be coded: 

CYCLE = number 

specifies a number of output records (to be written as output or made available 
to an exit routine) that are treated as a group by the INDEX keyword. Whenever 
this field has been used in the construction of the specified number of records, it 
is modified as specified in the INDEX parameter. For example, if CYCLE = 3 is 
coded, output records might appear as 111 222 333 444 etc. This parameter 
can be coded only when INDEX is coded. If CYCLE is omitted and INDEX is 
coded, a CYCLE value of 1 is assumed; that is, the field is indexed after each 
inclusion in a potential output record. 

RANGE = number 

specifies an absolute value which the contents of this field can never exceed. If 
an index operation attempts to exceed the specified absolute value, the contents 
of the field as of the previous index operation are used. 

INPUT = ddname 

specifies the ddname for the input data set. 

FROMLOC = number 

specifies the location of the selected field within the input logical record. The 
number represents the position in the input record. If, for example, FROMLOC = 10 
is coded, the specified field begins at the tenth byte; if FROMLOC = 1 is coded, the 
field begins at the first byte. (For variable records, significant data begins on the 
first byte after the four-byte length descriptor.) 

Some of the FD keywords do not apply when certain patterns or pictures are selected 
by the user; for example, the INDEX, CYCLE, RANGE, and SIGN parameters are used 
only with numeric fields. Figure 21 shows which lEBDG keywords can be used with the 
applicable pattern or picture chosen by the user. Each keyword should appear no 
more than once on any FD statement. 
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Figure 21. Compatible lEBDG Operations 
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CREATE Statement 



The CREATE statement defines the contents of a record (or records) to be made 
available to a user routine or to be written directly as an output record (or records). 

The format of the CREATE statement is: 

: [/abe/] CREATE { [QUANTITY = number] } 1 

{[,FILL.= {^character'} 

{X'2-hexadeclmal-digits'}}} 
{[.INPUT = {ddname} \ 

{SYSIN[(cccc)] }]} j 

{[.PICTURE = /engt/),start/oc, {'character-sfr/ng' } I 

{P'decimal-number' } ] 

{B'decimal-number' }]} 
{[.NAME= {name} 

{{namel,namen...)} 
{(name,(COPY = namel,namen...))}]} 
{ [, EXIT = routinename] } 
where: 

QUANTITY = number 

specifies the number of records that this CREATE statement is to generate; each 
record is specified by the other parameters. If QUANTITY is omitted and INPUT is 
not specified, only one output record is created. If QUANTITY is omitted and INPUT 
is specified, the number of records created is equal to the number of records in the 
input data set. If both QUANTITY and INPUT are coded, and the quantity specified 
is greater than the number of records in the input data set, the number of records 
created is equal to the number of input records to be processed plus the generated 
data up to the specified number. 

FILL = 

specifies a value that is to be placed in each byte of the output record before any 
other operation in the construction of record. If FILL Is not coded, binary zeros are 
placed in the output record. These values can be coded: 

'character' 

specifies an EBCDIC character that is to be placed in each byte of the output 
record. 

X'2-hexadecimal-digits' 

specifies two hexadecimal digits (for example, FILL = X'40', or FILL = X'FF') to 
be placed in each byte of the output record. 

INPUT = 

defines an input data set whose records are to be used in the construction of 
output records. If INPUT is not coded, the output records are created entirely from 
utility control statements. If INPUT is coded, QUANTITY should also be coded, 
unless the remainder of the input records are all to be processed by this CREATE 
statement. These values can be coded: 

ddname 

specifies the ddname of a DD statement defining an input data set. 

SYSIN[(cccc)] 

specifies that the SYSIN data set (input stream) contains records (other than 
utility control statements) to be used in the construction of output records. If 
SYSIN is coded, the Input records follow this CREATE statement (unless the 
CREATE statement is in a REPEAT group, in which case the input records follow 
the last CREATE statement of the group). When INPUT = SYSIN is coded, the 
input records are delimited from any additional utility control statements by a 
record containing $$$E in columns 1 through 4. If "(cccc)" coded, the input 
records are delimited by a record containing EBCDIC characters beginning in 
column 1; the cccc can be any combination of from one to four EBCDIC 
characters. 

PICTURE = 

specifies the length, starting byte, and contents of a user-supplied picture (CREATE 
statement picture). If both PICTURE and NAME are omitted, the fill character 
specified in the CREATE statement appears in each byte of applicable output 
records. These values can be coded: 

length 

specifies the number of bytes that the picture will occupy. 



lEBDG Program 89 



startloc 

specifies a starting byte (within any applicable output record) in which the 
picture is to begin. 

'character-string' 

specifies an EBCDIC character string that is to be placed in the applicable 
record(s). The character string is left aligned at the defined starting byte. A 
character string may be broken in column 71 and continued in column 4. 

P'dec/ma/-number' 

specifies a decimal number that is to be converted to packed decimal and 
placed right aligned (within the boundaries of the defined length and starting 
byte) in the output records. 

B 'decimal-number' 

specifies a decimal number that is to be converted to binary and placed right 
aligned (within the boundaries of the defined length and starting byte) in the 
output records. 

NAME = 

specifies the name or names of previously defined fields to be included in the 
applicable output records. If both NAME and PICTURE are omitted, the fill character 
specified in the CREATE statement appears in each byte of the applicable output 
record. These values can be coded: 

(namel,...) 

specifies the name or names of a field or fields to be included in the applicable 
output record(s). Each field is included in an output record in the order in which 
its name is encountered in the CREATE statement. 

COPY = number 

indicates that all fields named in the inner parentheses (maximum of twenty) are 
to be treated as a group and included the specified number of times in each 
output record produced by this CREATE statement. Any number of sets of inner 
parentheses can be included with NAME; however, sets of parentheses cannot 
be embedded. Within each set of inner parentheses, COPY must appear before 
the name of any field. 

EXIT = routinename 

specifies the name of a user routine that is to receive control from lEBDG before 
writing each output record. 

After processing each potential output record, the user routine provides a return code 
to instruct lEBDG how to handle the output record. The user codes are: 

• 00, which specifies that the record is to be written. 

• 04, which specifies that the record is not to be written. The skipped record is not to 
be counted as a generated output record; processing is to continue as though a 
record were written. If skips are requested through user exits and input records are 
supplied, each skip causes an additional input record to be processed in the 
generation of output records. For example, if a CREATE statement specifies that 
ten output records are to be generated and a user exit indicates that two records 
are to be skipped, 12 input records are processed. 

• 12, which specifies that the processing of the remainder of this set of utility control 
statements is to be bypassed. Processing is to continue with the next DSD 
statement. 

• 16, which specifies that all processing is to halt. 

Note: When an exit routine is loaded and when the user returns control to lEBDG, 
register one contains the address of the first byte of the output record. Each keyword 
should appear no more than once on any CREATE statement. 

Figure 22 shows the addition of field X to two different records. In this example, field x 
does not have a special starting location. In record 1, field X is the first field referred 
to by the CREATE statement; therefore, field X begins in the first byte of the output 
record. In record 2, two fields, field A and field B, have already been referred to by a 
CREATE statement; field X, the next field referred to, begins immediately after field B. 

The user can also indicate that a numerical field is to be modified after it has been 
referred to n times by a CREATE statement or statements, that is, after n cycles, a 
modification is to be made. A modification will add a user-specified number to a field. 

The CREATE statement constructs an output record by referring to previously defined 
fields by name and/or by providing a picture to be placed in the record. The user can 
generate multiple records with a single CREATE statement. 
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Figure 22. Default Placement of Fields Within an Output Record Using lEBDG 

When defining a picture in a CREATE statement, the user must specify its length and 
starting location in the output record. The specified length must be equal to the 
number of specified EBCDIC or numeric characters. (When a specified decimal number 
is converted to packed decimal or binary, it is automatically right aligned.) 

Figure 23 shows three ways in which output records can be created from utility control 
statements. 
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Figure 23. Creating Output Records with Utility Control 



As an alternative to creating output records from utility control statements alone, the 
user can provide input records, which can be modified and written as output records. 
Input records can be provided directly in the input stream, or in a data set. 

As previously mentioned, the CREATE statement is responsible for the construction of 
an output record. An output record is constructed in the following order: 

1. A fill character, specified or default (binary zero), is initially loaded into each byte 
of the output record. 

2. An input record, if any is provided, is left aligned in the output record. 

3. FD fields, if any, are placed in the output record in the order of the appearance of 
their names in the CREATE statement. 

4. A CREATE statement picture, if any, is placed in the output record. 

lEBDG provides a user exit so that the user can provide his own routine to analyze or 
further modify a newly constructed record before it is placed in the output data set. 

A set of utility control statements contains one DSD statement, any number of FD, 
CREATE, and REPEAT statements, and one END statement when the INPUT parameter 
is omitted from the FD card. 
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REPEAT Statement 



When selecting fields from an input record (FD INPUT = ddname), the field must be 
defined by an FD statement within each set of utility control statements. In this case, 
defined fields for field selection are not usable across sets of utility control 
statements. The FD card may be duplicated and used in more than one set of utility 
control statements within the job step. 

The REPEAT statement specifies the number of times a CREATE statement or group of 
CREATE statements is to be used repetitively in the generation of output records. The 
REPEAT statement precedes the CREATE statements to which it applies. 

Figure 24 shows a group of five CREATE statements repeated n times. 

''^*^.^jQ.''!P^^.°t'^^^...^^^I^L?^^'!!I'^"lJ'^.- ■ V -V 

ilabefl REPEAT QUANTltY - r)umber[,CREATE ^mtrr^r] 




CREATE (1) 
CREATE (2) 
CREATE (3) 
CREATE (4) 
CREATE (5) 

CREATE (1) 
CREATE (2) 
CREATE (3) 
CREATE (4) 
CREATE (51 



END Statement 



CREATE (1) 
CREATE (2) 
. CREATE (3) 
CREATE (4) 
CREATE (5) 

Figure 24. Repetition Due to the REPEAT Statement Using lEBDG 

where: 

QUANTITY = number 

specifies the number of times the defined group of CREATE statements is to be 
used repetitively. This number cannot exceed 65,535. 

CREATE = number 

specifies the number of following CREATE statements to be included in the group. If 
the CREATE parameter is omitted, only one CREATE statement is repeated. 

The END statement is used to mark the end of a set of utility control statements. Each 
set of control statements can pertain to any number of input data sets and a single 
output data set. 

The format of the END statement is: 

■ ilabel] END 



92 Utilities (Release 21.7) 



lEBDG Examples 



lEBDG Example 1 



The following examples illustrate some of the uses of lEBDG. Table 16 can be used as 
a quick reference guide to lEBDG examples. The numbers in the "Example" column 
point to examples that follow. 



Table 16. lEBDG Example Directory 






Operation 


Data Set 
Organization 


Device 


Comments 


Example 


Place binary zeros in 
selected fields. 


Sequential 


9-track tape 


Blocked input and output. 


1 


Ripple alphabetic 
pattern 


Sequential 


9-track tape, 
2314 Disk 


Blocked input and output. 


2 


Create output records 
from utility control 
statements 


Sequential 


2314 Disk 


Blocked output. 


3 


Modify records from 
partitioned members 
and input stream 


Partitioned, 
Sequential 


2314 Disk 


Reblocking is performed. Each 
block of output records contains 
ten modified partitioned input 
records and two input stream 
records. 


4 


Create partitioned 
members for utility 
control statements 


Partitioned 


2314 Disk 


Blocked output. One set of 
utility control statements per 
member. 


5 


Roll and wave user- 
supplied patterns 


Sequential 


2311 Disk 


Output records are created 
from utility control statements. 


6 


Create indexed 
sequential data set 
using field selection 
and data generation 


Sequential, 

Indexed 

sequential 


2314 Disk 


Output records are created by 
augmenting selected input 
fields with generated data. 


7 



In this example, binary zeros are to be placed in two fields of records copied from a 
sequential data set. After the operation, each record in the copied data set (OUTSET) 
contains binary zeros in locations 20 through 29 and 50 through 59. 

The example follows: 

//CLEAROUT JOB , , MSGLEVEL= 1 

// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 

//SEQIN DD DSNAME=INSET,UNIT=2400,DISP=( OLD, KEEP), 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 ) , 



// 

//SEQOUT DD 

// 
// 
//SYSIN DD 

DSD 

FD 

FD 

FD 

CREATE 

END 



VOLUME=SER=240000,LABEL=( ,NL) 

DSNAME=OUTSET,UNIT=2400,VOLUME=SER=240001 , 
DCB=(RECFM=FB,LRECL=80,BLKSIZE=800), 
DISP=( ,KEEP),LABEL=( ,NL) 

* 

OUTPUT=( SEQOUT ) , INPUT=( SEQIN ) 
NAME=FIELD1 , INPUT=SEQIN, LENGTH=80 
NAME=FIELD2 , LENGTH=1 , STARTLOC=20 
NAME=FIELD3 , LENGTH= 1 , STARTLOC=50 
QUANTITY=1,00,INPUT=SEQIN,NAME=(FIELD1 , 
FIELD2, FIELDS ) 



nc 



/* 

The control statements are discussed below: 

• SEQIN DD defines a sequential input data set (INSET). The data set was originally 
written on a 9-track, unlabeled tape volume. 

• SEQOUT DD defines the test data set (OUTSET). The output records are identical 
to the input records, except for locations 20 through 29 and 50 through 59, which 
contain binary zeros at the completion of the operation. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to the DD 
statements defining the input and output data sets. 

• The first FD statement defines an 80 byte field of input data. 

• The second and third FD statements create two ten-byte fields (FIELD and FILED3) 
that contain binary zeros. The fields are to begin in the 20th and 50th bytes of 
each output record. 
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lEBDG Example 2 



lEBDG Example 3 



• CREATE constructs 100 output records in which the contents of previously defined 
fields (FIELDl, FIELD2, and FIELDS) are placed in their respective starting locations 
in each of the output records. Input records from data set INSET are used as the 
basis of the output records. 

• END signals the end of a set of utility control statements. 

In this example, a ten-byte alphabetic pattern is to be rippled. At the end of the job 
step the first output record contains "ABCEDFGHIJ", followed by data in location 11 
through 80 from the input record; the second record contains "BCDEFGHIJK" 
followed by data in locations 11 through 80, etc. 

The example follows: 

//RIPPLE JOB ,,MSGLEVEL=1 

// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 

//SEQIN DD DSNAME=INSET, DISP=( OLD, KEEP ),VOL=SER=240000, 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=800 ),UNIT=2400 

//SEQOUT DD DSNAME=OUTSET,UNIT=2314,VOLUME=SER=231400, 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=800), 

// DISP=( ,KEEP),SPACE=(TRK,(20,10) ) 

//SYSIN DD * 

DSD OUTPUT=( SEQOUT ) , INPUT=( SEQIN ) 

FD NAME=FIELD 1 , INPUT=SEQIN , LENGTH=80 

FD NAME=FIELD2,LENGTH=10,FORMAT=AL,ACTION=RP, UC 
STARTLOC= 1 

CREATE QUANTITY=100,INPUT=SEQIN,NAME=( FIELD1 ,FIELD2 ) 

END 
/* 

The control statements are discussed below: 

• SEQIN DD defines an input sequential data set (INSET). The data set was originally 
written on a 9-track, standard labeled tape volume. 

• SEQOUT DD defines the test output data set (OUTSET). Twenty tracks of primary 
space and ten tracks of secondary space are allocated for the sequential data set 
on a 2314 volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to the DD 
statements defining the input and output data sets. 

• The first FD statement defines an 80 byte field of input data. 

• The second FD statement creates a ten-byte field in which the pattern 
ABCEDFGHIJ is placed. The data is rippled after each output record is written. 

• CREATE constructs 100 output records in which the contents of a previously 
defined field (FIELDl) are included. The CREATE statement uses input records from 
data set INSET as the basis of the output records. 

• END signals the end of a set of utility control statements. 

In this example, output records are to be created entirely from utility control 
statements. Three fields are to be created and used in the construction of the output 
records. In two of the fields, alphabetic data is to be truncated; the other field is a 
numeric field that is to be indexed by one after each output record is written. Figure 
25 shows the contents of the output records at the end of the job step. 



Field 1 
1 


Field 2 
31 


Field 3 (packed dec 
61 71 


imal) 
80 




ABCDEFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZABCD 






123. 


.90 




BCDEFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZABC 






123 . 


.91 




CDEFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZAB 






123 . 


.92 




DEFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZA 






123 . 


.93 




EFGHIJKLMNOPQRSTUVWXYZABCD 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 






123 . 


.94 




Figure 25. Output Records at Job Step Completion 
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The example follows: 



lEBDG Example 4 



//UTLYONLY JOB ,,MSGLEVEL=1 
// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 

//SEQOUT DD DSNAME=OUTSET,UNIT=2311,DISP=( ,KEEP), 
// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 ) , 

// SPACE=(TRK,(20,10 ) ) , VOLUME=SER=240000 

DATA 




The control statements are discussed below: 

• SEQOUT DD defines the test output data set. Twenty tracks of primary space and 
ten tracks of secondary space are allocated for the sequential data set on a 2311 
volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to the DD 
statement defining the output data set. 

• FD defines the contents of three fields to be used in the construction of output 
records. The first field contains 30 bytes of alphabetic data to be truncated left 
after each output record is written. The second field contains 30 bytes of 
alphabetic data to be truncated right after each output record is written. The third 
field is a ten-byte field containing a packed decimal number (1234567890) to be 
incremented by one after each record is written. 

• CREATE constructs 100 output records in which the contents of previously defined 
fields (FIELDl, FIELD2, and FIELD3) are included. 

• END signals the end of a set of utility control statements. 

In this example, two partitioned members and input records from the input stream are 
to be used as the basis of a partitioned output member. Each block of 12 output 
records is to contain ten modified records from an input partitioned member and two 
records from the input stream. Figure 26 shows the content of the output partitioned 
member at the end of the job step. 

The example follows: 



//MIX 

// 

//SYSPRINT 

//PARIN1 

// 

// 

//PARIN2 

// 
// 
//PAROUT 

// 

// 

//SYSIN 
DSD 
FD 

REPEAT 
CREATE 
CREATE 



JOB , , MSGLEVEL= 1 

EXEC PGM=IEBDG 

DD SYSOUT=A 

DD DSNAME=INSET1 ( MEMBA ) , UNIT=23 1 4 , DISP=OLD , 

DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 , DSORG=PS ) , 

VOLUME=SER=23 1400 
DD DSNAME=INSET2 ( MEMBA ) , UNIT=2 314, DISP=OLD , 

DCB( RECFM=FB , LRECL=80 , BLKSIZE=960 , DSORG=PS ) , 

VOLUME=SER=231401 
DD DSNAME=PARSET(MEMBA),UNIT=2314,DISP=( ,KEEP), 

VOLUME=SER=231402,SPACE=(TRK,( 20,10,5) ), 

DCB( RECFM=FB , LRECL=80 , BLKSIZE=960 , DSORG=PS ) 
DD DATA 

OUTPUT=( PAROUT ) , INPUT=( PARIN1 ,PARIN2 ) 
NAME=FIELD1 , LENGTH=1 3 ,PICTURE=1 3 , 'DEPARTMENT 21 ' 
QUANTITY= 1 , CREATE=2 

QUANTITY=10,INPUT=PARIN1 ,NAME=FIELD1 
QUANTITY=2 , INPUT=SYSIN 



(input records 1 through 20) 

$$$E 

REPEAT 
CREATE 
CREATE 



QUANTITY=1 , CREATE=2 

QUANTITY= 1 , INPUT=PARIN2 , NAME=FIELD 1 

QUANTITY=2 , INPUT=SYSIN 



(input records 21 through 40) 

$$$E 

END 
/* 
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lEBDG Example 5 
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Input record 1 



(Rightmost 67 bytes of INSET1 (MEMBA) record 1) 



(Rightmost 67 bytes of INSET1 (MEMBA) record 10) 
from input stream 



Input record 2 from input stream 
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Input record 3 from input stream 11 

Input record 4 from input stream 12 
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Input record 19 from input stream 11 

Input record 20 from input stream 12 

Department 21 (Rightmost 67 bytes of 1NSET2 (MEMBA) record 1) 



Department 21 (Rightmost 67 bytes of INSET2 (MEMBA) record 10} 

Input record 21 from input stream 1 1 

Input record 22 from input stream 12 



Output Records 
1 1st block of 12 
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1 10th block of 12 

10 
11 
12 

1 11th block of 12 



Figure 26. Output Partitioned Member at Job Step Completion 

The control statements are discussed below: 

PARINl DD defines one of the input partitioned members. 

PARIN2 DD defines the second of the input partitioned members. (Note that the 
members are from different partitioned data sets.) 

PAROUT DD defines the output partitioned member. This example assumes that the 
partitioned data set does not exist prior to the job step; that is, this DD statement 
allocates space for the partitioned data set. 

SYSIN DD defines the control data set, which follows in the input stream. 

DSD marks the beginning of a set of utility control statements and refers to the DD 
statements defining the input and output data sets. 

FD creates a 13-byte field in which the picture "DEPARTMENT 21" is placed. 

The first REPEAT statement indicates that the following group of two CREATE 
statements is to be repeated ten times. 

The first CREATE statement creates ten output records. Each output record is 
constructed from an input record (from partitioned data set INSETl) and from 
previously defined FIELDl. 

The second CREATE statement indicates that two records are to be constructed 
from input records included next in the input stream. 

The $$$E record separates the input records from the REPEAT statement. The next 
REPEAT statement group is identical to the preceding group, except that records 
from a different partitioned member are used as input. 

END signals the end of a set of utility control statements. 

In this example, output records are to be created from three sets of utility control 
statements and written in three partitioned data set members. Four fields are to be 
created and used in the construction of the output records. In two of the fields 
(FIELDl and FIELD3), alphabetic data is to be shifted. The other two fields are to be 
fixed alphameric and zoned decimal fields. Figure 27 shows the partitioned data set 
members at the end of the job step. 
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Figure 27. Partitioned Data Set IVIembers at Job Step Completion 
The example follows: 



JOB 
EXEC 
DD 
DD 



DD 



DD 



DD 



//UTSTS 

//• 

//SYSPRINT 

//PAROUT 1 

// 

// 

//PAROUT 2 

// 

// 

//PAROUT 3 

// 

// 

//SYSIN 

DSD 

FD 

FD 

FD 

FD 

CREATE 

END 

DSD 

CREATE 

END 

DSD 

CREATE 

END 

/* 

The control statements are discussed below: 

• PAROUT 1 DD defines the first member (MEMBA) of the partitioned output data set. 
This example assumes that the partitioned data set does not exist prior to this job 
step; that is, this DD statement allocates space for the data set. 

• PAR0UT2 and PAR0UT3 DD define the second and third members, respectively, of 
the output partitioned data set. Note that each DD statement specifies DISP = OLD 
and UNIT = AFF = PAROUTl. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to the DD 
statement defining the member applicable to that set of utility control statements. 

• FD defines the contents of a field that is used in the subsequent construction of 
output records. 

• CREATE constructs four records from combinations of previously defined fields. 

• END signals the end of a set of utility control statements. 



, ,MSGLEVEL=1 
PGM=IEBDG 
SYSOUT=A 

DSNAME=PARSET( MEMBA ) , UNIT=23 1 4 , DISP=( , KEEP ) , 
VOLUME=SER=23 1 400 , SPACE=( TRK, (10,10,5)), 
DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 , DSORG=PS ) , 

DSNAME=PARSET( MEMBB ) , UNIT=AFF=PAROUT 1 , 
DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 , DSORG=PS ) , 
DISP=OLD , VOLUME=SER=23 1 400 

DSNAME=PARSET( MEMBC ) ,UNIT=AFF=PAR0UT1 , 
DCB=( RECFM=FB , LRECL=80 , BLKSIZE=800 , DSORG=PS ) , 
DISP=OLD , V0LUME=SER=2 3 1400 
DATA 
OUTPUT=( PAROUTl ) 

NAME=FIELD1 , LENGTH=30 , FORMAT=AL, ACTION=SL 
NAME=FIELD2 , LENGTH=20 , FORMAT=ZD 
NAME=FIELD3 , LENGTH=20 , FORMAT=AL, ACTION=SR 
NAME=FIELD4 , LENGTH-30 , FORMAT=AN 
QUANTITY=4,NAME=(FIELD1 ,FIELD3 ,FIELD2 ) 

0UTPUT=(PAR0UT2 ) 

QUANTITY=4 , NAME=( ( C0PY=3 , FIELD3 ) , FIELD2 ) 

OUTPUT=( PAR0UT3 ) 
QUANTITY=4,NAME=( FIELD4, FIELD 1 ) 
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lEBDG Example 6 



In this example, ten fields containing user-supplied EBCDIC pictures are to be used in 
the construction of output records. After a record is written, each field is rolled or 
waved, as specified in the applicable FD statement. Figure 28 shows the contents of 
the output records at the end of the job step. 
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Figure 28. 


Contents of Output Records at Job Step Completion 









The example follows: 

//ROLLWAVE JOB , , MSGLEVEL= 1 
// EXEC PGM=IEBDG 

//SYSPRINT DD SYSOUT=A 
//OUTSET 
// 
// 

//SYSIN 
DSD 



DD 



DD 



FD 
FD 
FD 
FD 
FD 
FD 
FD 
FD 
FD 
FD 



AAAAA 


,ACTION=RO 


BBBBB 


,ACTI0N=RO 


A AA 


,ACTI0N=RO 


BB B 


,ACTI0N=RO 


AAA 


,ACTrON=RO 


CCCCC 


,ACTrON=WV 


DDDD 


,ACTION=WV 


C CC 


,ACTrON=WV 


DD D 


,ACTrON=WV 


' CCC 


' , ACTION=WV 



nc 



DSNAME=SEQSET,UNIT=231 1 ,DISP=( ,KEEP), 
VOLUME=SER=231 1 , SPACE=( TRK, ( 20, 10 ) ), . 
DCB=(RECFM=FB,LRECL=80,BLKSIZE=800 ) 

* 

OUTPUT=( OUTSET) 

NAME=FIELD 1 , LENGTH=8 , PICTURE=8 , 

NAME=FIELD2 , LENGTH=8 , PICTURE=8 , 

NAME=FIELD3 , LENGTH=8 , PICTURE=8 , 

NAME=FIELD4 , LENGTH=8 , PICTURE=8 , 

NAME=FIELD5 , LENGTH=8 , PICTURE=8 , 

NAME=FIELD6 , LENGTH=8 , PICTURE=8 , 

NAME=FIELD7 , LENGTH=8 , PICTURE=8 , 

NAME=FIELD8 , LENGTH=8 , PICTURE=8 , 

NAME=FIELD9 , LENGTH-8 , PICTURE=8 , 

NAME=FIELD1 , LENGTH=8 , PICTURE=8 , 
CREATE QUANTITY=300 , NAME=( FIELD1 , FIELD2 , FIELD3 , FIELD4 , 

FIELDS , FIELDS , FIELD7 , FIELD8 , FIELD9 , FIELDl ) 
END 
/* 

The control statements are discussed below: 

• OUTSET DD defines the output sequential data set on a 2311 volume. Twenty 
tracks of primary space and ten tracks of secondary space are allocated to the 
data set. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to the DD 
statement defining the output data set. 

• FD defines a field to be used in the subsequent construction of output records. 
Note that the direction and frequency of the initial roll or wave depends on the 
location of data in the field. 

• CREATE constructs 300 records from the contents of the previously defined fields. 

• END signals the end of a set of utility control statements. 
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lEBDG Example 7 In this example, the first ten bytes of the output record contain zoned decimal format 

generated data. This field serves as the key field for the output record in the output 
indexed sequential data set. The key field is incremented (indexed) by one for each 
record. The input sequential data set provides an additional 80-byte field to complete 
the output record. 

The example follows: 

//CREATEIS JOB MSGLEVEL=1 

//BEGIN EXEC PGM=IEBDG 

//TAPEIN DD DCB=(BLKSIZE=80,LRECL=80,RECFM=F), 

// DISP=( OLD, KEEP ),UNIT=2400,LABEL=( ,SL), 

// DSNAME=TAPEIT,VOL=SER=MASTER 

//DISKOUT DD DCB=(BLKSIZE=270,LRECL=90,RECFM=FB, 

// DSORG=IS , NTM=2 , OPTCD=MY , RKP=0 , KEYLEN= 1 , 

// CYL0FL=1 ),UNIT=2314,SPACE={CYL, 1 ), 

// VOL=SER=23 1 400 , DSNAME=CREATIS , DISP=( NEW, KEEP ) 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DSD OUTPUT=( DISKOUT ) , INPUT=( TAPEIN ) 

FD NAME=DATAFD , LENGTH=80 , FROMLOC= 1 , STARTLOC= 11, UC 
INPUT=TAPEIN 

FD NAME=KEYFD , LENGTH= 1 , STARTLOC= 1 , FORMAT=ZD , INDEX= 1 

CREATE INPUT=TAPEIN , NAME=( KEYED , DATAFD ) 

END 
/* 

The control statements are discussed below: 

• TAPEIN DD defines the sequential input data set. 

• DISKOUT DD defines the indexed sequential output data set. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• DSD marks the beginning of a set of utility control statements and refers to the DD 
statement defining the output data set. 

• FD defines a field that will be used in the subsequent construction of output 
records. The first FD statement in this example defines and locates an 80-byte field 
of input data. The data is field selected from one of the input logical records and 
placed at start location 11 of the output logical record. The second FD statement 
defines and locates the ten-byte key field. 

• CREATE constructs a 90-byte output record by referring to the previously defined 
fields. 

• END signals the end of a set of utility control statements. 
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lEBEDIT Program 



Input and Output 



Control 

Job Control Statements 

Restrictions 

Utility Control Statement 

EDIT Statement 



lEBEDIT is a data set utility used to create an output data set containing a selection of 
jobs or job steps. (See "Introduction" for general data set utility information.) At a 
later time, the data set can be used as an input stream for job processing. 

lEBEDIT creates an output job stream by editing and selectively copying a job stream 
provided as input. The program can copy: 

• An entire job or jobs, including JOB statements and any associated JOBLIB 
statements. 

o Selected job steps, including the JOB statement and any associated JOBLIB 
statement. 

All selected JOB statements, JOBLIB statements, jobs, or job steps are placed in the 
output data set in the same order as they exist in the input data set. Note that a 
JOBLIB statement is copied only if it follows a selected JOB statement. 

When lEBEDIT encounters a selected job step containing an input record having the 
characters "..*" in columns 1 through 3, the program automatically converts that 
record into a termination statement (/* statement) and places it in the output data 
set. 

lEBEDIT uses the following input: 

o An input data set, which is a sequential data set consisting of a job stream. The 
input data set is used as source data in creating an output sequential data set. 

• A control data set, which contains utility control statements that are used to specify 
the organization of jobs and job steps in the output data set. 

lEBEDIT produces the following output: 

• An output data set, which is a sequential data set consisting of a resultant job 
stream. 

e A message data set, which is a sequential data set that contains applicable control 
statements, error messages, if applicable, and, optionally, the output data set. 

lEBEDIT provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that an error occurred. The output data set may not be usable 
as a job stream. Processing continues. 

o 08, which indicates that an unrecoverable error occurred while attempting to 
process the input, output, or control data set. The job step is terminated. 

lEBEDIT is controlled by job control statements and utility control statements. The job 
control statements are required to execute or invoke the program and to define the 
data sets used and produced by the program. The utility control statements are used 
to control the functions of the program. 

Table 17 shows the job control statements necessary for using lEBEDIT. 

The minimum region size that can be specified for lEBEDIT is lOK. 

• The block size for the SYSPRINT data set must be a multiple of 121. The block size 
for the SYSIN, SYSUTl, and SYSUT2 data sets must be a multiple of 80. Any 
blocking factor can be specified for these block sizes. 

lEBEDIT is controlled through the EDIT utility control statement. 

The EDIT statement indicates which step or steps of a specified job in the input data 
set are to be included in the output data set. Any number of EDIT statements can be 
included in an operation, thus including selected jobs in the output data set. 

EDIT statements must be included in the same order as the input jobs that they 
represent. If no EDIT statement is present in the control data set, the entire input data 
set is copied. 
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Table 17. lEBEDIT Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = lEBEDIT) or, if the job control statements 

reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a system 
output device, a tape volume, or a direct access volume. 

SYSUTl DD Defines a sequential input data set on a card reader, a tape volume, or a direct 
access device. 

SYSUT2 DD Defines a sequential output data set on a card punch, printer, tape volume, or 
direct access device. 

SYSIN DD Defines the control data set. The data set normally is included in the input 

stream; however, it can be defined as a member of a procedure library or as a 
sequential data set existing somewhere other than in the input stream. 

The format of the EDIT statement is: 

I ilabefimj [START = /obname] 
I [JYPE = I POSITION }] 

{INCLUDE } 
{EXCLUDE } 
[,STEPNAME = ({name-name } [, {name-name }},...) 
{name } I, {name }]] 



[.NOPRINT] 



where: 



START = jobname 

specifies the name of the input job to which the EDIT statement applies. (Each EDIT 
statement must apply to a separate job.) If START is specified without TYPE and 
STEPNAME, the JOB statement and all job steps for the specified job are included 
in the output. If START is omitted and only one EDIT statement is provided, the first 
job encountered in the input data set is processed. If START is omitted from an 
EDIT statement other than the first statement, processing continues with the next 
JOB statement found in the input data set. 

TYPE = 

specifies the contents of the output data set. If TYPE is omitted, TYPE = POSITION 
is assumed. These values can be coded: 

POSITION 

specifies that the output is to consist of a JOB statement, the job step specified 
in the STEPNAME parameter, and all steps that follow it. All job steps preceding 
the specified step are omitted from the operation. This is the default. 

INCLUDE 

specifies that the output data set is to contain a JOB statement and all job steps 
specified in the STEPNAME parameter. 

EXCLUDE 

specifies that the output data set is to contain a JOB statement and all jobs 
steps belonging to job except those steps specified in the STEPNAME 
parameter. 

STEPNAME = 

specifies the first job step to be placed in the output data set when coded with 
TYPE = POSITION. Job steps preceding this step are not copied to the output data 
set. When coded with TYPE = INCLUDE or TYPE = EXCLUDE, STEPNAME specifies 
the names of job steps that are to be included in or excluded from the operation. 
For example, STEPNAME = (STEPA,STEPF-STEPL,STEPZ) indicates that job steps 
STEPA, STEPF through STEPL, and STEPZ are to be included in or excluded from 
the operation. If STEPNAME is omitted, the entire input job whose name is specified 
on the EDIT statement is copied. If no job name is specified, the first job 
encountered is processed. 

NOPRINT 

specif ies that the message data set is not to include a listing of the output data set. 
If NOPRINT is omitted, the resultant output is listed in the message data set. 

Note: Any JOBLIB DD statement that follows a selected JOB statement is 
automatically copied to the output data set. 
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lEBEDIT Examples 



The following examples show some of the uses of lEBEDIT. Table 18 can be used as a 
quick-reference guide to lEBEDIT examples. The numbers in the "Example" column 
point to examples that follow. 



Table 18. lEBEDIT Example Directory 



lEBEDIT Example 1 



lEBEDIT Example 2 



Opei'ation Devices 



COPY 



COPY 



COPY 



COPY 



COPY 



9-track tape 
7-track tape 



2311 Disk, 
9-track tape 

2314 or 2319 
Diski 

9-track tape 



Comments 

The input data set contains three jobs. One job is 
to be copied. 

The output data set is the second data set on the 
volume. One job step is to be copied from each of 
three jobs. 

Include a job step from one job and exclude a 
job step from another job. 

Latter portion of a job stream is to be copied. 

All records in the input data set are to be copied. 
The ..* record is converted to a /* statement in 
the output data set. 



Example 



1 The 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 2314 in the 
control statement. 

In this example one job (JOBA), including all of its job steps (A, B, C, and D), is to be 
copied into the output data set. The input data set contains three jobs: JOBA, which 
has four job steps; JOBB, which has three job steps; and JOBC, which has two job 
steps. 

The example follows: 



//EDIT1 JOB 

// EXEC 

//SYSPRINT DD 

//SYSUT1 DD 

//SYSUT2 DD 
// 
// 



09#440, SMITH 

PGM=IEBEDIT 

SYSOUT=A 

UNIT=2400 , DISP=( OLD , KEEP ) , VOLUME=SER=00 1 234 

UNIT=2400,DISP=( NEW, KEEP ),VOLUME=SER=00 1235, 
DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) , 
DSNAME=OUTTAPE 



DD 
EDIT 



START=JOBA 



//SYSIN 

/* 

The control statements are discussed below: 



• SYSUTl DD defines the input data set. The data set resides on a 9-track, standard 
labeled tape volume (001234). 

• SYSUT2 DD defines the output data set. The data set is to reside as the first data 
set on a standard labeled, 9-track tape volume (001235). 

• SYSIN DD defines the control data set, which follows in the input stream. 

• EDIT indicates that JOBA is to be copied in its entirety. 

This example copies: (1) the JOB statement and steps STEPC and STEPD for JOBA, 
(2) the JOB statement and STEPE for JOBB, and (3) the JOB statement and STEPJ for 
JOBC. The input data set contains three jobs: JOBA, which includes STEPA, STEPB, 
STEPC, and STEPD; JOB B, which includes STEPE, STEPF, and STEPG; and JOBC, 
which includes STEPH and STEPJ. 

The example follows: 

//EDIT2 JOB 09#440, SMITH 

// EXEC PGM=IEBEDIT 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DISP=( OLD, KEEP ),VOLUME=SER=00 1234, 

// UNIT=2400-2 

//SYSUT2 DD DSNAME=OUTSTRM,UNIT=2400-2,DISP=( NEW, KEEP), 

// DCB=(DEN=1 ,RECFM=F,LRECL=80,BLKSIZE=80, 

// TRTCH=C),LABEL=(2,SL) 



//SYSIN 



DD 
EDIT 
EDIT 
EDIT 



START=JOBA , TYPE=INCLUDE , STEPNAME=STEPC , STEPD 
START=JOBB , TYPE=INCLUDE , STEPNAME=STEPE 
START=JOBC , TYPE=INCLUDE , STEPNAME=STEPJ 
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lEBEDIT Example 3 



lEBEDIT Example 4 



The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 7-track, standard 
labeled tape volume (001234). 

• SYSUT2 DD defines the output data set. The data set is to reside as the second 
data set on a 7-track, standard labeled tape volume (001235). 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The EDIT statements copy the indicated JOB statements and job steps. 

This example copies: (1) the JOB statement and steps STEPF and STEPG for JOBB 
and (2) the JOB statement and STEPH, excluding STEPJ, for JOBC. The input data set 
contains three jobs: JOBA, which includes STEPA, STEPB, STEPG, and STEPD; JOBB, 
which includes STEPE, STEPF, and STEPG; and JOBC, which Includes STEPH and 
STEPJ. 

The example follows: 

//EDIT3 JOB 09#440, SMITH 

// EXEC PGM=IEBEDIT 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=INSET,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER=231400 

//SYSUT2 DD DSNAME=OUTTAPE , UNIT=2400 , LABEL( , NL) , 

// DCB=(DEN=2,RECFM=F,LRECL=80,BLKSIZE=80 ), 

//• DISP=( ,KEEP) 

//SYSIN DD * 

EDIT START=JOBB , TYPE=INCLUDE , STEPNAME=STEPF-STEPG 
EDIT START=JOBC , TYPE=EXCLUDE , STEPNAME=STEPJ 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 2314 volume 
(231400). 

• SYSUT2 DD defines the output data set. The data set is to reside as the first or 
only data set on an unlabeled, 9-track (800 bits per inch) tape volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The EDIT statements copy selected JOB statements and job steps. 

This example copies the JOBA JOB statement, the job step STEPF, and all the steps 
that follow it. The input data set contains one job (JOBA), which includes STEPA, 
STEPB, . . . STEPL. Job steps STEPA through STEPE are not included in the output 
data set. 

The example follows: 

//EDIT4 JOB 09#440, SMITH 

// EXEC PGM=IEBEDIT 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=INSTREAM,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER=231400 

//SYSUT2 DD DSNAME=OUTSTREM,UNIT=2314,DISP=( ,KEEP), 

// DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) , 

// VOLUME=SER=23 1 401, SPACE=.( TRK, 2 ) 

//SYSIN DD * 

EDIT START=JOBA,TYPE=POSITION,STEPNAME=STEPF 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 2314 or 2319 
volume (231400). 

• SYSUT2 DD defines the output data set. The data set is to reside on a 2314 volume 
(231401). Two tracks are allocated for the output data set. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• EDIT copies the JOB statement and job steps STEPF through STEPL. 
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lEBEDIT Example 5 This example copies the entire input (SYSUTl) data set. The record containing the 

characters "..*" in columns 1 through 3 is converted to a " /*" statement in the 
output data set. 

The example follows: 

//EDITS JOB 09#440, SMITH 

// EXEC PGM=IEBEDIT 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=OUTTAPE,UNIT=2400,VOLUME=SER=001234, 

// DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) , DISP=( NEW, KEEP ) 

//SYSIN DD DUMMY 

//SYSUTl DD DATA 

//BLDGDGIX JOB 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=2311 ,V0LUME=SER=1 1 1 111 ,DISP=OLD 

//SYSIN DD * 

BLDG INDEX=A.B.C,ENTRIES= 10, EMPTY 

/* 

The control statements are discussed below: 

• SYSUT2 DD defines the output data set. The data set is to reside as the first data 
set on a 9-track tape volume (001234). 

• SYSIN DD defines a dummy control data set. 

• SYSUTl DD defines the input data set, which follows in the input stream. The job is 
terminated when the termination statement (/*) is encountered. 
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lEBGENER Program-Class C 



Creating a Backup 
Copy 



Producing a Partitioned 
Data Set from 
Sequential Input 



Expanding a Partitioned 
Data Set 



Producing an Edited 
Data Set 



lEBGENER is a data set utility used to copy a sequential data set or a partitioned 
member, or to create a partitioned data set from a sequential or partitioned member 
used as input. (See "Introduction" for general data set utility information.) lEBGENER 
can be used to expand an existing partitioned data set by creating partitioned 
members and merging them into the data set that is to be expanded. 

lEBGENER provides optional editing facilities and exits for user routines that process 
labels, manipulate input data, create keys, and handle permanent input/output errors. 
Refer to "Appendix A: Exit Routine Linkage" for a discussion of linkage conventions 
that are applicable when user routines are provided. 

lEBGENER can be used to: 

• Create a backup copy of a sequential data set or a partitioned member. 

• Produce a partitioned data set from sequential input. 

• Expand a partitioned data set. 

• Produce an edited sequential or partitioned data set. 

• Reblock or change the logical record length of a data set. 

• Create user labels on sequential output data sets. 

At the completion or termination of lEBGENER, the highest return code encountered 
within the program is passed to the calling program. 

A backup copy of a sequential data set or partitioned member can be produced by 
copying the data set or member to any IBM-supported output device. For example, a 
copy can be made from tape to tape, from direct access to tape, etc. 

A data set that resides on a direct access volume can be copied to its own volume, 
provided that its data set name is changed. A partitioned data set cannot reside on a 
magnetic tape volume. 

lEBGENER can be used to produce a partitioned data set from sequential output. 
Through the use of utility control statements, the user can logically divide the 
sequential data set into record groups and assign member names to the record 
groups. lEBGENER places the newly created members in a partitioned output data set. 

Note: A partitioned data set cannot be produced if an input or output data set 
contains spanned records. 

Figure 29 shows how a partitioned data set is produced from a sequential data set 
used as input. The left-hand side of the figure shows the sequential data set. Utility 
control statements are used to divide the sequential data set into record groups and 
to provide a member name for each record group. The right-hand side of the figure 
shows the partitioned data set produced from the sequential input. 

An expanded data set is a data set into which an additional member or members 
have been merged. lEBGENER creates the members from sequential input and places 
them in the data set being expanded. The merge operation — the ordering of the 
partitioned directory — is automatically performed by the program. 

Figure 30 shows how sequential input is converted into members that are merged into 
an existing partitioned data set. The left-hand side of the figure shows the sequential 
input that is to be merged with the partitioned data set shown in the middle of the 
figure. Utility control statements are used to divide the sequential data set into record 
groups and to provide a member name for each record group. The right-hand side of 
the figure shows the expanded partitioned data set. Note that members B, D, and E 
from the sequential data set were placed in available space and that they are 
sequentially ordered in the partitioned directory. 

lEBGENER can be used to produce an edited sequential or partitioned data set. 
Through the use of utility control statements, the user can specify editing information 
that applies to a record, a group of records, selected groups of records, or an entire 
data set. 



lEBGENER Program - Class C 1 07 



Sequential 
input 



Utility control statennent 
names first member 



Utility control statement 
identified last record 



Utility control statement 
names new member 



Utility control statement 
identified last record 



Utility control statement 
names new member 



LASTREC 1 



LASTREC 2 



Record 

group 

1 




LASTREC n 



LASTREC n 



Record 
group 



Figure 29. Creating a Partitioned Data Set from Sequential Input Using lEBGENER 

An edited data set can be produced by: 

e Rearranging or omitting defined data fields witliin a record. 

• Supplying literal information as replacement data. 

• Converting data from packed decimal to unpacked decimal mode, unpacked 
decimal to packed decimal mode, or H-set BCD to EBCDIC mode. 



Sequential 
input 



Utility control'statements 
define record groups 
Name members 



LASTREC 



Member 
D 



LASTREC 



Member 
F 




Figure 30. Expanding a Partitioned Data Set Using lEBGENER 

Figure 31 shows part of an edited sequential data set. The left-hand side of the figure 
shows the data set before editing is performed. Utility control statements are used to 
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identify the record groups to be edited and to supply editing information. In this figure, 
literal replacement information is supplied for information within a defined field. (Data 
is rearranged, omitted, or converted in the same manner.) The BBBB field in each 
record in the record group is to be replaced by CCCC. The right-hand side of the 
figure shows the data set after editing. 
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Figure 31. Editing a Sequential Data Set Using lEBGENER 



Control 



Note: lEBGENER cannot be used to edit a data set if the input and output data sets 
consist of VS or VBS records and have equal block sizes and logical record lengths. In 
this case, any utility control statements that specify editing are ignored; lEBGENER 
performs a straight copy; that is, for each physical record read from the input data 
set, the utility writes an unedited physical record on the output data set. 

lEBGENER can be used to produce a reblocked output data set containing either 
fixed or variable records. In addition, the program can produce an output data set 
having a logical record length that differs from the input logical record length. 

lEBGENER uses the following input: 

• An input data set, which contains the data that is to be copied, edited, converted 
into a partitioned data set, or converted into members to be merged into an 
existing data set. The input is either a sequential data set or a member of a 
partitioned data set. 

• A control data set, which contains utility control statements. The control data set is 
required if editing is to be performed or if the output data set is to be a partitioned 
data set. 

lEBGENER produces the following output: 

• An output data set, which can be either sequential or partitioned. The output data 
set can be either a new data set (created during the current job step) or an existing 
partitioned data set that is to be expanded. 

• A message data set, which contains informational messages (for example, the 
contents of utility control statements) and any error messages. 

lEBGENER provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates probable successful completion. A warning message is written. 

• 08, which indicates that processing was terminated after the user requested 
processing of user header labels only. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

• 16, which indicates that a user routine passed a return code of 16 to lEBGENER. 
The job step is terminated. 

lEBGENER is controlled by job control statements and utility control statements. The 
job control statements are required to execute or invoke lEBGENER and to define the 
data sets that are used and produced by the program. The utility control statements 
are used to control the functions of lEBGENER. 
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Job Control Statements 



Table 19 shows the job control statements necessary for using lEBGENER. 



Restrictions 



Table 19. lEBGENER Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = lEBGENER) or, if the job control 

statements reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a 

system output device, a tape volume, or a direct access volume. 

SYSUTl DD Defines the input data set. It can define a sequential data set or a member of 

a partitioned data set. 

SYSUT2 DD Defines the output data set. It can define a sequential data set, a member of a 

partitioned data set, or a partitioned data set. 

SYSIN DD Defines the control data set, or specifies DUMMY when the output is 

sequential and no editing is specified. The control data set normally resides in 
the input stream; however, it can be defined as a member within a library of 
partitioned members. 

The minimum region size that can be specified for the execution of lEBGENER is 
14K + b, where b is the largest block size in the job step rounded to the next higher 
2K. 

lEBGENER always uses two buffers regardless of what was specified in the DCB. 

If both the SYSUTl and the SYSUT2 DD statements specify standard user labels 
(SUL), lEBGENER copies user labels from SYSUTl to SYSUT2. See "Appendix E: 
Processing User Labels" for a discussion of the available options for user label 
processing. 

Both the input data set and the output data set can contain fixed, variable, undefined, 
or variable spanned records. These records can be reblocked by the specification of a 
new maximum block length on the SYSUT2 DD statement. During reblocking, if the 
output data set resides on a direct access volume: 

• For fixed or variable records, keys can be retained only by using the appropriate 
user exit. 

• For variable spanned records, keys can never be retained. 

When the input/output data set has fixed length, variable length, or variable spanned 
records, the block size, the logical record length, and the record format are required. 
When the input/output data set has undefined records, only the block size is required. 

Refer to OS Data Management Services Guide, GC26-3746, for information on 
estimating space allocations. 

• The SYSPRINT DD statement is required for each use of lEBGENER. 

• The block size for the SYSPRINT data set must be a multiple of 121. The block size 
for the SYSIN data set must be a multiple of 80. Any blocking factor can be 
specified for these block sizes. 

• Space must be allocated for an output data set (SYSUT2 DD statement) that is to 
reside on a direct access device unless the data set is an expanded data set, in 
which case space must not be allocated. 

• DCB parameters in a SYSUT2 DD statement defining an expanded partitioned data 
set must be compatible with the specifications made when the data set was 
originally created. 

• Concatenated data sets with unlike attributes are not allowed as input to 
lEBGENER. For information on concatenated data sets, see OS Data l\/lanagement 
Services Guide, GC26-3746. 

• The SYSIN DD statement is required for each use of lEBGENER. 

• RECFM (except for undefined data sets), BLKSIZE, and LRECL (except for 
undefined data sets) must be specified on the SYSUT1/SYSUT2 DD statement 
when the data set is new and when the data set is a dummy data set, a card punch, 
or a printer. 

• When neither RECFM, BLKSIZE, nor LRECL are present for the input data set, these 
values are copied from the input data set. 

• Always specify the output BLKSIZE when the LRECL and RECFM (except for U) is 
specified. The default RECFM is U for the output data set. The output LRECL must 
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utility Control Statements 



GENERATE Statement 



EXITS Statement 



be present when editing is to be performed and the RECFM is either FB, VS, or 
VBS. In other cases a default LRECL value is generated by lEBGENER. 

• The Input data set must always have a BLKSIZE parameter. The default RECFM is U 
for the input data set. The input LRECL must be specified when RECFM is either VS, 
VBS, or FB. In other cases a default LRECL is generated by lEBGENER. 

lEBGENER is controlled by utility control statements. The statements and the order in 
which they must appear are: 

• GENERATE statement, which is used to indicate the number of member names and 
alias names, record identifiers, literals, and editing information contained in the 
control data set. 

• EXITS statement, which is used to indicate that user routines are provided. 

• LABELS statement, which is used to specify user-label processing. 

• MEMBER statement, which is used to specify the member name and alias of a 
member of a partitioned data set to be created. 

• RECORD statement, which is used to define a record group to be processed and to 
supply editing information. 

The control statements are included in the control data set as required. If no utility 
control statements are included in the control data set, the entire input data set is 
copied sequentially. 

When the output is to be sequential and editing is to be performed, one GENERATE 
statement and as many RECORD statements as required are used. If user exits are 
provided, an EXITS statement is used. 

When the output is to be partitioned, one GENERATE statement, one MEMBER 
statement per output member, and RECORD statements, as required, are used. If user 
exits are provided, an EXITS statement is used. 

The GENERATE statement is used when: (1) output is to be partitioned, (2) editing is 
to be performed, or (3) user routines are provided and/or label processing is 
specified. 

The GENERATE statement must appear before other statements. If it contains errors 
or is inconsistent with other statements, lEBGENER is terminated. 

The format of the GENERATE statement is: 

[/abel] GENERATE [MAXNAME = n] 
E.MAXFLDS = n] 
[.MAXGPS = n] 
[.MAXLITS = n] 
where: 

MAXNAME = n 

specifies a number that is no less than the total number of member names and 
aliases appearing in subsequent MEMBER statements. MAXNAME is required if 
there are one or more MEMBER statements. 

MAXFLDS = n 

specifies a number that is no less than the total number of FIELD parameters 
appearing in subsequent RECORD statements. MAXFLDS is required if there are any 
FIELD parameters in subsequent RECORD statements. 

MAXGPS = n 

specifies a number that is no less than the total number of IDENT parameters 
appearing in subsequent RECORD statements. MAXGPS is required if there are any 
IDENT parameters in subsequent RECORD statements. 

MAXLITS = n 

specifies a number that is no less than the total number of characters contained in 
the FIELD literals of subsequent RECORD statements. MAXLITS is required if the 
FIELD parameters of subsequent RECORD statements contain literals. MAXLITS 
does not pertain to literals used in IDENT parameters. 

The EXITS statement is used to identify exit routines supplied by the user. Linkages to 
and from exit routines are discussed in "Appendix A: Exit Routine Linkage." 

The EXITS statement is used when user routines are provided. 
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The format of the EXITS statement is: 

[ " "ilabei] EJcifs -^^j^j^^^j^^r^'^'^Y'^^'"''^'"' ' ----'■'■—— — — •: 

[.OUTHDR = routinename] 
I [,INTLR = rout/nename] 

I [,OUTTLR = routinename} 

[,KEY = routinename} 

[,DATA = routinename] 

[.lOERROR = rout/nename] ; 

? [,TOTAL « (routinename,size)] ^ ■ 

where: 

INHDR = routinename 

specifies the symbolic name of a routine that processes user input header labels. 

OUTHDR = rouf/nename 

specifies the symbolic name of a routine that creates user output header labels. 
OUTHDR is ignored if the output data set is partitioned. 

INTLR = routinename 

specifies the symbolic name of a routine that processes user input trailer labels. 

OUTTLR = routinename 

specifies the symbolic name of a routine that processes user output trailer labels. 
OUTTLR is ignored if the output data set is partitioned. 

KEY = routinename 

specifies the symbolic name of a routine that creates the output record key. (This 
routine does not receive control when a data set consisting of VS or VBS type 
records is processed because no processing of keys is permitted for this type of 
data.) 

DATA = rout/nename 

specifies the symbolic name of a routine that modifies the physical record (logical 
record for VS or VBS type records) before it is processed by lEBGENER. 

lOERROR = routinename 

specifies the symbolic name of a routine that handles permanent input/output error 
conditions. 

TOTAL = 

specifies that exits to a user's routine are to be provided prior to writing each 
record. The keyword OPTCD = T must be specified for the SYSUT2 DD statement. 
TOTAL is valid only when the utility is used to process sequential data sets. These 
values must be coded: 

routinename 

specifies the name of a user-supplied totaling routine. 

size 

specifies the number of bytes needed to contain totals, counters, pointers, etc. 

For a detailed discussion of the processing of user labels as data set descriptors, and 
for discussion of user label totaling), refer to "Appendix E: Processing User Labels." 

The LABELS statement specifies whether or not user labels are to be treated as data 
by lEBGENER. For a detailed discussion of this option, refer to "Processing User 
Labels as Data," in "Appendix E: Processing User Labels." 

The LABELS statement is used when the user wants to specify that: (1) no user labels 
are to be copied to the output data set, (2) user labels are to be copied to the output 
data set from records in the data portion of the SYSIN data set, or (3) user labels are 
to be copied to the output data set after they are modified by the user's label 
processing routines. If more than one valid LABELS statement is included, all but the 
last LABELS statement are ignored. 

The format of the LABELS statement is: 

[/abe/] LABELS [DATA = {YES } 

{NO } 

{ALL } 

{ONLY } 



{INPUT }] 
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RECORD Statement 



where: 

DATA = 

specifies whether user labels are to be treated as data by lEBGENER. These values 
can be coded: 



YES 



specifies that any user labels that are not rejected by a user's label-processing 
routine are to be treated as data. Processing of labels as data ends in 
compliance with standard return codes. If no value is entered, YES is assumed. 



NO 



specifies that user labels are not to be treated as data. 



ALL 



specifies that user labels in the group currently being processed are to be 
treated as data regardless of any return code. A return code of 16 causes 
lEBGENER to complete processing the remainder of the group of user labels and 
to terminate the job step. 

ONLY 

specifies that only user header labels are to be treated as data. User header 
labels are processed as data regardless of any return code. The job terminates 
upon return from the OPEN routine. 

INPUT 

specifies that user labels for the output data set are supplied as 80-byte input 
records in the data portion of SYSIN. The number of input records that should be 
treated as user labels must be identified by a RECORD statement. 

Note: LABELS DATA = NO must be specified to make standard user label (SUL) exits 
inactive when input/output data sets with nonstandard labels (NSL) are to be 
processed. 

The MEMBER statement is used when the output is to be partitioned. One MEMBER 
statement must be included for each member to be created by lEBGENER. The 
MEMBER statement provides the name and aliases of a member that is to be created. 

All RECORD statements following a MEMBER statement pertain to the member named 
in that MEMBER statement. If no MEMBER statements are included, the output data 
set is organized sequentially. 

The format of the MEMBER statement is: 



[/abe/] MEMBER NAME = (name[,a//as]...) \ 

where: 

NAME = (name[,a//as]...) 

specifies a member name followed by a list of its aliases. If only one name appears 
in the statement, it need not be enclosed in parentheses. 

The RECORD statement is used to define a record group and to supply editing 
information. A record group consists of records that are to be processed identically. 

The RECORD statement is used when: (1) the output is to be partitioned, (2) editing is 
to be performed, or (3) user labels for the output data set are to be created from 
records in the data portion of the SYSIN data set. The RECORD statement defines a 
record group by identifying the last record of the group with a literal name,. 

If no RECORD statement is used, the entire input data set or member is processed 
without editing. More than one RECORD statement may appear in the control 
statement stream for lEBGENER. 

Within a RECORD statement, one IDENT parameter can be used to define the record 
group; one or more FIELD parameters can be used to supply the editing information 
applicable to the record group; and one LABELS parameter can be used to indicate 
that this statement is followed immediately by output label records. 

The format of the RECORD statement is: 

: [/abe/] RECORD {[IDENT = (/engff7,'name',/npuf-/ocaffon)]} ; 

{[,FIELD = ([/ength], [fnput-/ocat(on ],[convers/on], i 

[output-location]). ..],['Hteral']} 

{[.LABELS = n]} : 
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where: 

IDENT = 

identifies the last record of the input group to which the FIELD parameters or 
MEMBER statement applies. If the RECORD statement is not followed by additional 
RECORD or MEMBER statements, IDENT also defines the last record to be 
processed. If IDENT is omitted, the remainder of the input data is considered to be 
in onie record group; subsequent RECORD and MEMBER statements are ignored. 
These values can be coded: 

length 

specifies the length (in bytes) of the identifying name. The length cannot exceed 
eight characters. 

'name' 

specifies the exact literal that identifies the last input record of a record group. 
If no match for name is found, the remainder of the input data is considered to 
be in one record group; subsequent RECORD and MEMBER statements are 
ignored. 

input-location 

specifies the starting location of the field that contains the identifying name in 
the input records. 

FIELD = 

specifies field-processing and editing information. Only the contents of specified 
fields in the input record is copied to the output record. The values that can be 
coded are: 

length 

specifies the length (in bytes) of the input field or literal to be processed. If 
length is not specified, a lengfth of 80 bytes is assumed. If a literal is to be 
processed, a length of 40 bytes or less must be specified. 

/nput-/ocaf/on 

specifies the starting byte of the field to be processed. If input-location is not 
specified, byte 1 is assumed. 

'literal' 

specifies a literal (maximum length of 40 bytes) to be placed in the specified 
output location. If a literal contains apostrophes, each apostrophe must be 
written as two consecutive apostrophes. 

conversion 

specifies a two- byte code that indicates the type of conversion to be performed 
on this field. If no conversion is specified, the field is moved to the output area 
without change. The values that can be coded are: 

PZ 

specifies that data (packed decimal) is to be converted to unpacked decimal 
data. 

ZP 

specifies that data (unpacked decimal) is to be converted to packed decimal 
data. 

HE 

specifies that data (H-set BCD) is to be converted to EBCDIC. 

output-location 

specifies the starting location of this field in the output records. If output-location 
is not specified, byte 1 is assumed. 

LABELS = n 

is an optional parameter that indicates the number of records in the SYSIN data set 
to be treated as user labels. The number n, which is a number from 1 to 8, must 
specify the exact number of label records that follow the RECORD statement. If this 
parameter is included, DATA = INPUT must be coded on a LABELS statement 
before it in the input stream. 

If conversion is specified In FIELD, the following restrictions apply: 

• PZ-type (packed-to-unpacked) conversion is impossible for packed decimal 
records longer than 16K bytes. 

• For ZP-type (unpacked-to-packed) conversion, the normal 32K-byte maximum 
applies. 
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• When the ZP parameter Is specified, the conversion is performed in place. The 
original unpacked field is replaced by the new packed field. Therefore, the ZP 
parameter must be omitted from subsequent references to that field. If the field is 
needed in its original unpacked form, it must be referenced prior to the use of the 
ZP parameter. 

If conversion is specified in the FIELD parameter, the length of the output record can 
be calculated for each conversion specification. When L is equal to the length of the 
input record, the calculation is made, as follows: 

• For a PZ (packed-to-unpacked) specification, 2L - 1. 

• For a ZP (unpacked-to-packed) specification, (L/2) + C. If L is an odd number, C 
is 1/2; if L is an even number, C is 1. 

• For an HE (H-set BCD to EBCDIC) specification, L 

If both output header labels and output trailer labels are to be contained in the SYSIN 
data set, the user must include one RECORD statement (including the LABELS 
parameter), indicating the number of input records to be treated as user labels, for 
header labels and one for trailer labels. The first such RECORD statement indicates 
the number of user header labels; the second indicates the number of user trailer 
labels. If only output trailer labels are included in the SYSIN data set, a RECORD 
statement must be included to indicate that there are no output header labels in the 
SYSIN data set (LABELS = 0). This statement must precede the RECORD LABELS = n 
statement which signals the start of trailer label input records. 

For a detailed discussion of the LABELS option, refer to "Processing User Labels As 
Data," in "Appendix E: Processing User Labels." 

Note: IDENT and FIELD parameters are ignored in straight copy processing of data 
sets that contain VS or VBS records. 

The examples that follow illustrate some of the uses of lEBGENER. Table 20 can be 
used as a quick reference guide to lEBGENER examples. The numbers in the 
"Example" column point to the examples that follow. 



Table 20. 1 


EBGENER Example Directory 






Operation 


Data Set 
Organization 


Devices 


Comments 


Example 


COPY 


Sequential 


Card Reader, 
Tape 


Blocked output. 


1 


Copy -with 
editing 


Sequential 


Card Reader, 
Tape 


Blocked output. 


2 


COPY -with 
editing 


Sequential 


Card Reader, 
Tape 


Blocked output. Input includes 
// cards. 


3 


COPY -with 
editing 


Sequential 


Card Reader, 
2311 Disk 


Blocked output. Input includes 
// cards. 


4 


PRINT 


Sequential 


Card Reader, 
Printer 


Input includes // cards. System 
output device is a printer 


5 


CONVERT 


Sequential 
input, 
Partitioned 
output 


Tape, 
2314 Disk 


Blocked output. Three members 
are to be created, 


6 


Copy -with 
editing 


Sequential 


2301 Drum 


Blocked output. Two members are 
to be merged into existing data set. 


7 


COPY -with 
editing 


Sequential 


Tape 


Blocked output. Data set edited as 
one record group. 


8 


COPY -with 
editing 


Sequential 


2314 Disk 


Blocked output. New record length 
specified for output data set. Two 
record groups specified. 


9 


COPY -with 
editing 


Sequential 


Tape 


Blocked output. Data set edited as 
one record group. 


10 
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In this example, a card- 
volume. 



in 



put, sequential data set is to be copied to a 9-track tape 
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The example follows: 

//CDTOTAPE JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DUMMY 

//SYSUT2 DD DSNAME=OUTSET,UNIT=2400,LABEL=( ,SL), 

// DISP=( ,KEEP),VOLUME=SER=001234, 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 

//SYSUT1 DD * 

(input card data set) 

/* 

The control statements are discussed below: 

• SYSIN DD defines a dummy data set. No editing is to be performed; therefore, no 
utility control statements are needed. 

• SYSUT2 DD defines the output data set. The data set is written to a 9-track tape 
volume at a density of 800 bits per inch. The data set is to reside as the first (or 
only) data set on the volume. 

• SYSUTl DD defines the card-input data set. The data set can contain no // cards. 

In this example, a card-input, sequential data set is to be copied to a 7-track tape 
volurne. The control data set is a member of a partitioned data set. 

The example follows: 

//CDTOTAPE JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DSNAME=CNTRLIBY(STMNTS),UNIT=231 1 , 

// DISP=( OLD, KEEP ),V0LUME=SER=1 11112, 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=OUTSET,UNIT=2400-2,LABEL=( ,SL), 

// DCB=(DEN=1 ,RECFM=FB,LRECL=80,BLKSIZE=2000, 

// TRTCH=C),DISP=( ,KEEP),VOLUME=SER=001234 

//SYSUTl DD * 

(input card data set) 

/* 

The control statements are discussed below: 

• SYSIN DD defines the control data set, which contains the utility control 
statements. The control statements reside as a member, STMNTS, in a partitioned 
data set. 

o SYSUT2 DD defines the output data set. The data set is written as the first or only 
data set on the volume. It is written at 556 bits per inch density on a 7-track tape 
volume. 

• SYSUTl DD defines the card-input data set. The data set can contain no // cards. 

In this example, a card-input, sequential data set is to be copied to a 9-track tape 
volume. The input contains cards that have slashes (//) in columns 1 and 2. The 
control data set is a member of a partitioned data set. 

The example follows: 

//CDTOTAPE JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DSNAME=CNTRLIBY( STMNTS ),UNIT=2314, 

// DISP=( OLD, KEEP ),V0LUME=SER=1 11112, 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80) 

//SYSUT2 DD DSNAME=OUTSET,UNIT=2400,LABEL=(2,SL), 

// VOLUME=SER=00 1234, DCB=( RECFM=FB , 

// LRECL=80,BLKSIZE=2000 ),DISP=( ,KEEP) 

//SYSUTl DD DATA 

(input card data set, including // cards) 

/* 
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The control statements are discussed below: 

• SYSIN DD defines the data set containing the utility control statements. The 
statements reside as a member, STMNTS, in a partitioned data set. 

• SYSUT2 DD defines the copied sequential data set (output). The data set is written 
as the second data set on the specified tape volume. 

• SYSUTl DD defines the card-input data set. The data set is to be edited as 
specified in the utility control statements (not shown). The input data set contains 
// cards. 

In this example, a card-input, sequential data set is to be copied to a 2311 volume. 
The input data set contains // cards. 

The example follows: 

//CDTOTAPE JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DSNAME=CNTRLIBY( STMNTS ) , UNIT=23 1 1 , 

// DISP=( OLD, KEEP ) , V0LUME=SER=1 11112, 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ) 

//S YSUT2 DD DSNAME=OUTSET , UNIT=2 3 1 1 , VOLUME=SER= 111113, 

// DISP=( ,KEEP),SPACE=(TRK,(20,10) ), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 

//SYSUT1 DD DATA 

(input card data set, including // cards) 

/* 

The control statements are discussed below: 

• SYSIN DD defines the control data set, which contains the utility control 
statements. The control statements reside as a member, STMNTS, in a partitioned 
data set. 

o SYSUT2 DD defines the output data set. Twenty tracks of primary storage space 
and ten tracks of secondary space are allocated for the data set on a 2311 volume. 

• SYSUTl DD defines the card-input data set. The data set is to be edited as 
specified in the utility control statements (not shown). The input data set contains 
// cards. 

In this example, the content of a card data set is to be printed. The printed output is 
to be left aligned, with one 80-byte record appearing on each line of printed output. 

The example follows: 

//CDTOPTR JOB 
// EXEC 

//SYSPRINT DD 
//SYSIN DD 
//SYSUT2 DD 
//SYSUTl DD 



09#660, SMITH 

PGM=IEBGENER 

SYSOUT=A 

DUMMY 

SYSOUT=A,DCB= 

DATA 



:( RECFM=F , LRECL=80 , BLKSIZE=80 ) 



(input card data set, including // cards) 

/* 

The control statements are discussed below: 

• SYSIN DD defines a dummy data set. No editing is to be performed; therefore, no 
utility control statements are required. 

o SYSUT2 DD indicates that the output is to be written on the system output device 
(printer). Carriage control can be specified by changing the RECFM = F 
subparameter to RECFM = FA. 

• SYSUTl DD defines the input card data set. The input data set contains // cards. 
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lEBGENER Example 6 



lEBGENER Example 7 



GENERATE 
MEMBER 
RECORD 
MEMBER 
GROUP 2 RECORD 



GROUP 1 



In this example, a partitioned data set (consisting of three members) is to be created 
from sequential input. 

The example follows: 

//TAPEDISK JOB 09#660, SMITH 

// EXEC PGM= lEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INSET,UNIT=2400,LABEL=( ,SL), 

// DISP=( OLD , KEEP ) , VOLUME=SER=00 1 234 , 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=NEWSET,UNIT=2314,DISP=( ,KEEP), 

// V0LUME=SER=1 11112, SPACE=( TRK, (20,10,5)), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 

//SYSIN DD * 

MAXNAME=3 ,MAXGPS=2 

NAME=MEMBER1 

IDENT= ( 8 , • FIRSTMEM ' , 1 ) 

NAME=MEMBER2 

IDENT=( 8 , • SECNDMEM' , 1 ) 
MEMBER NAME=MEMBER3 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set (INSET). The data set was originally written 
on a 9-track tape volume at 800 bits per inch density. 

• SYSUT2 DD defines the output partitioned data set (NEWSET). The data set is to be 
placed on a 2314 volume. Twenty tracks of primary space, ten tracks of secondary 
space, and five blocks (256 bytes each) of directory space are allocated to allow 
for future expansion of the data set. The output records are blocked to reduce the 
space required by the data set. 

• SYSIN DD defines the control data set, which follows in the input stream. The utility 
control statements are used to create members from sequential input data; the 
statements do not specify any editing. 

• GENERATE indicates that: (1) three member names are included in subsequent 
MEMBER statements and (2) the IDENT parameter appears twice in subsequent 
RECORD statements. 

• The first MEMBER statement assigns a member name (MEMBERl) to the first 
member. 

• The first RECORD statement (GROUPl) identifies the last record to be placed in 
the first member. The name of this record (FIRSTMEM) appears in bytes 1 through 
8 of the input record. 

• The remaining MEMBER and RECORD statements define the second and third 
members. 

In this example, sequential input is to be converted into two partitioned members. The 
newly created members are to be merged into an existing partitioned data set. User 
labels on the input data set are to be passed to the user exit routines. 

The example follows: 

//DRUMDRUM JOB 09#660, SMITH 
// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=INSET,UNIT=2301 ,DISP=( OLD, KEEP), 
// VOLUME=SER= 111112, DCB=( RECFM=FB , LRECL=80 , 
// BLKSIZE=20000),LABEL=( ,SUL) 

//SYSUT2 DD DSNAME=EXISTSET,UNIT=2301 ,DISP=( MOD, KEEP), 
// V0LUME=SER=11 1 1 13,DCB=(RECFM=FB,LRECL=80, 
// BLKSIZE=2000 ) 
//SYSIN DD * 

GENERATE 
EXITS 
MEMBER 
GROUPl RECORD 
MEMBER 
/* 
The control statements are discussed below: 

• SYSUTl DD defines the input data set (INSET). The input data set, which resides on 
a 2301 volume, has standard and user labels. 



MAXNAME=3 , MAXGPS= 1 
INHDR=R0UT1 , INTLR=R0UT2 
NAME= ( MEMX , ALI ASX ) 
IDENT=(8, 'FIRSTMEM' ,1 ) 
NAME=MEMY 
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• SYSUT2 DD defines the output partitioned data set (EXISTSET). The members 
created during this job step are merged into the partitioned data set. The output 
records are blocl<ed to reduce the space required by the new members. 

• SYSIN DD defines the control data set, which follows in the input stream. The utility 
control statements are used to create members from sequential input data; the 
statements do not specify any editing. 

• GENERATE indicates that: (1) two member names and one alias are included in 
subsequent MEMBER statements and (2) an IDENT parameter appears in a 
subsequent RECORD statement. 

• EXITS defines the user routines that are to process user labels. 

• The first MEMBER statement assigns a member name (MEMX) and an alias 
(ALIASX) to the first member. 

• The first RECORD statement identifies the last record to be placed in the first 
member. The name of this record (FIRSTMEM) appears in bytes 1 through 8 of the 
input record. 

• The second MEMBER statement assigns a member name (MEMY) to the second 
member. The remainder of the input data set is included in this member. 

lEBGENER Example 8 In this example, a sequential input data set is to be edited and copied. 

The example follows: 

//TAPETAPE JOB 09 #660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSET,UNIT=2400-2,DISP=( OLD, KEEP), 

// VOLUME=SER=001234,LABEL=(3,SUL), 

// DCB=( RECFM=F, LRECL=80 ,BLKSIZE=80 , TRTCH=C ) , 

//SYSUT2 DD DSNAME=NEWSET,UNIT=2400-2,DISP=(NEW,PASS), 

// DCB=( RECFM=FB, LRECL=80 , BLKSIZE=2000 , TRTCH=C ) , 

// VOLUME=SER=001235,LABEL=( ,SL) 

//SYSIN DD * 

GENERATE MAXFLDS=3,MAXLITS=1 1 

RECORD FIELD=( 10, '**********', ,1 ), UC 

FIELD=( 5 , 1 , HE , 1 1 ) , FIELD=( 1 ,' = ',, 1 6 ) 
EXITS INHDR=R0UT1 ,0UTTLR=R0UT2 

LABELS DATA=INPUT 

RECORD LABELS=2 

(first header label record) 
(second header label record) 

RECORD LABELS=2 

(first trailer label record) 
(second trailer label record) 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the sequential input data set (OLDSET). The data set was 
originally written as the third data set (800 bits per inch) on a 7-track tape volume. 

• SYSUT2 DD defines the sequential output data set (NEWSET). The data set is 
written as the first or only data set on a 7-track tape volume. A density of 800 bits 
per inch and data conversion are specified for the write operation. The output 
records are blocked to reduce the space required by the data set and to reduce the 
access time required when the data set is subsequently referred to. The data set is 
passed to a subsequent job step. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• GENERATE indicates that: (1) a maximum of three FIELD parameters is included in 
subsequent RECORD statements and (2) a maximum of 11 literal characters are 
included in subsequent FIELD parameters. 

• EXITS indicates that the specified user routines require control when SYSUTl is 
opened and when SYSUT2 is closed. 

• LABELS indicates that labels are included in the input stream. 

• The first RECORD statement controls the editing, as follows: (1) asterisks are 
placed in positions 1 through 10, (2) bytes 1 through 5 of the input record are 
converted from H-set BCD to EBCDIC mode and moved to positions 11 through 15, 
and (3) an equal sign is placed in byte 16. 
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lEBGENER Example 9 



• The second RECORD statement indicates that the next two records from SYSIN 
should be written out as user header labels on SYSUT2. 

• The third RECORD statement indicates that the next two records from SYSIN 
should be written as user trailer labels on SYSUT2. 

Note: This example shows the relationship between the RECORD LABELS statement 
and the EXITS statement. lEBGENER attempts to write a first and second label trailer 
as user labels at close time of SYSUT2, but, before returning control to the system; 
the user routine R0UT2 can review these records and change them, if necessary. 

In this example, a sequential input data set is to be edited and copied. 

The example follows: 

//DISKDISK JOB 09#660, SMITH 
// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSET,UNIT=2314,DISP=(OLD,KEEP), 
// V0LUME=SER=1 1111 2 ,DCB=( RECFM=F , LRECL= 1 00 , BLKSIZE=1 00 ) 
//SYSUT2 DD DSNAME=NEWSET,UNIT=2314,DISP=(NEW,KEEP), 
// VOLUME=SER= 111113, DCB=( RECFM=FB , LRECL=80 , 
// BLKSIZE=640 ) , SPACE=( TRK, (20,10)) 
//SYSIN DD 
GENERATE 
EXITS 
GROUP 1 RECORD 



MAXFLDS=4 , MAXGPS= 1 
IOERROR=ERRORRT 
IDENT=( 8 , ' FIRSTGRP ' , 1 ) , 
FIELD=( 2 1 , 80 , , 60 ) , FIELD=( 59,1, 
FIELD=( 11 ,90, ,70),FIELD=(69,1 



GROUP 2 RECORD 
/* 

The control statements are discussed below: 



1 ) 
,1) 



«c 



• SYSUTl DD defines the input data set (OLDSET). The logical record length of the 
input records is 100 bytes. 

• SYSUT2 DD defines the output data set (OUTSET). Twenty tracks of primary 
storage space and ten tracks of secondary storage space are allocated for the data 
set on a 2314 volume. The logical record length of the output records is 80 bytes, 
and the output is blocked. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• GENERATE indicates that: (1) a maximum of four FIELD parameters is included in 
subsequent RECORD statements and (2) a maximum of one IDENT parameter 
appears in a subsequent RECORD statement. 

• EXITS identifies the user routine that handles input/output errors. 

• The first RECORD statement controls the editing of the first record group, as 
follows: (1) FIRSTGRP, which appears in bytes 1 through 8 of the input record, is 
defined as being the last record in the first group of records and (2) bytes 80 
through 100 of each input record are moved into positions 60 through 80 of each 
corresponding output record. (This example implies that bytes 60 through 79 of the 
input records in the first record group are no longer required; thus, the logical 
record length is shortened by 20 bytes.) The remaining bytes within each input 
record are transferred directly to the output records, specified in the second FIELD 
parameter. 

• The second RECORD statement indicates that the remainder of the input records 
are to be processed as the second record group. Bytes 90 through 100 of each 
input record are moved into positions 70 through 80 of the output records. (This 
example implies that bytes 70 through 89 of the input records from group 2 are no 
longer required; thus, the logical record length is shortened by 20 bytes.) The 
remaining bytes within each input record are transferred directly to the output 
records, specified in the second FIELD parameter. 

If the logical record length of the output data set differs from that of the input data 
set, as in this example, all positions in the output records must undergo editing to 
justify the new logical record length. 
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lEBGENER Example 10 In this example, a sequential input data set is to be edited and copied. 

The example follows: 

//TAPETAPE JOB 09#660, SMITH 

// EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSET,UNIT=2400,DISP=( OLD, KEEP), 

// VOLUME=SER=00 1234, LABEL=( 3 , SUL ) , DCB=( RECFM=F , 

// LRECL=80 , BLKSIZE=80 ) 

//SYSUT2 DD DSNAME=NEWSET,UNIT=2400,DISP=( NEW, PASS), 

// VOLUME=SER=001235,LABEL=( ,SUL), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 

//SYSIN DD * 

GENERATE MAXFLDS=3 , MAXLITS= 1 1 

RECORD FIELD=( 10, '**********',, 1 ), ttC 

FIELD=( 5 , 1 , HE , 1 1 ) , FIELD=( 1 ,' = ',, 1 6 ) 

LABELS DATA=INPUT 

RECORD LABELS=3 

(first header label record) 
(second header label record) 
(third header label record) 

RECORD LABELS=2 

(first trailer label record) 
(second trailer label record) 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set (OLDSET). The data set was originally 
written as the third data set (800 bits per inch) on a 9-track tape volume. 

• SYSUT2 DD defines the output data set (NEWSET). The data set is written as the 
first or only data set on a 9-track tape volume. A density of 800 bits per inch is 
specified for the write operation. The output records are blocked to reduce the 
space required by the data set and to reduce the access time required when the 
data set is subsequently referred to. The data set is passed to a subsequent job 
step. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• GENERATE indicates that: (1) a maximum of three FIELD parameters is included in 
subsequent RECORD statements and (2) a maximum of 11 literal characters are 
included in subsequent FIELD parameters. 

• LABELS indicates that label records are included in the input stream. 

• The first RECORD statement controls the editing, as follows: (1) asterisks are 
placed in positions 1 through 10, (2) bytes 1 through 5 of the input record are 
converted from H-set BCD to EBCDIC mode and moved to positions 11 through 15, 
and (3) an equal sign is placed in byte 16. 

• The second and third RECORD statements indicate that three 80-byte records 
(cards), to be written as user labels on the output data set, immediately follow. The 
first RECORD statement indicates that the following cards are to be treated as 
header labels. The second RECORD statement indicates that the following cards 
are to be treated as trailer labels. 
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Copying an Indexed 
Sequential Data Set 



Creating a Sequential 
Backup Copy 



lEBISAM is a data set utility used to copy an indexed sequential data set directly from 
one direct access volume to another. (See "Introduction" for general data set utility 
information.) 

Alternatively, lEBISAM can be used to reorganize an indexed sequential data set into a 
sequential (unloaded) data set and place that data set on a direct access or magnetic 
tape volume. The unloaded data set is in a form that can be subsequently loaded, that 
is, it can be converted back into an indexed sequential data set. 

Optionally, lEBISAM can be used to print the records of an indexed sequential data 
set. 

lEBISAM can be used to: 

• Copy an indexed sequential data set. 

• Create a sequential backup (transportable) copy of source data from an indexed 
sequential data set. 

• Create an indexed sequential data set from an unloaded data set. 

• Print an indexed sequential data set. 

At the completion or termination of lEBISAM, the highest return code encountered 
within the program is passed to the calling program. 

lEBISAM can be used to copy an indexed sequential data set directly from one 
direct access volume to another. When the data set is copied, the records marked for 
deletion are only deleted If the DELETE parameter was specified in the OPTCD 
(optional control program service) field. Those records that are contained in the 
overflow area of the original data set are moved into the primary area of the copied 
data set. The control information characteristics such as BLKSIZE and OPTCD can be 
overridden by new specifications. Caution should be used, however, when overriding 
these characteristics (see "Unloaded Data Sets" in this chapter). 

An unloaded sequential data set can be created to serve as a backup or 
transportable copy of source data from an indexed sequential data set. When the 
unloaded data set is created, the records marked for deletion are only deleted if the 
DELETE parameter was specified in the OPTCD field. When the data set is 
subsequently loaded — reconstructed into an indexed sequential data set — records that 
were contained in the overflow area assigned to the original data set are moved 
sequentially into the primary area. 

An unloaded data set consists of 80-byte logical records. The data set contains: 

• Fixed records from an indexed sequential data set. 

• Control information used in the subsequent loading of the data set. 

Control information consists of characteristics that were assigned to the indexed 
sequential data set. These characteristics are: 

• Optional control program service (OPTCD) 

• Record format (RECFM) 

• Logical record length (LRECL) 

• Block size (BLKSIZE) 

• Relative key position (RKP) 

• Number of tracks in cylinder index (NTM) 

• Key length (KEYLEN) 

• Number of overflow tracks on each cylinder (CYLOFL) 

When a load operation is specified, these characteristics can be overridden by new 
specifications in the DCB parameter of the SYSUT2 DD statement (refer to "Job 
Control Statements" for a discussion of the SYSUT2 DD statement). Caution should 
be used, however, because checks are made to ensure that: 

1. Record format is the same as that of the original indexed sequential data set 
(either fixed or variable length). 

2. Logical record length is greater than or equal to that of the original indexed 
sequential data set when the RECFM is V or VB. 
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Creating an indexed 
Sequentiai Data Set from 
an Unioaded Data Set 



Printing the Logicai 
Records of an indexed 
Sequentiai Data Set 



3. For fixed records, tlie blocl^ size is equal to or a multiple of tiie logical record length 
of the records in the original indexed sequential data set. For variable records, the 
block size is equal to or greater than the logical record length plus four. 

4. Relative l<ey position is equal to or less than the logical record length minus the l<ey 
length. Following are relative key position considerations: 

• If the RECFM is variable (V) or variable blocl<ed (VB), the relative i^ey position 
should be at least 4. 

• If the DELETE parameter was specified in the OPTCD field and the RECFM is 
fixed or fixed t}locl<ed, the relative key position should be at least 1. If the 
DELETE parameter was specified in the OPTCD field and the RECFIVI is V or VB, 
the relative l<ey position should be at least 5. 

5. The l<ey length is less than or equal to 255 bytes. 

6. For a fixed unblocked data set with relative key position equal to zero, the LRECL is 
the length of the data. In all other cases, the LRECL is the length of the key plus the 
data. When changing the record format from fixed unblocked and RKP = to fixed 
blocked, the output LRECL value must be equal to the input LRECL plus the input 
key length. 

If either RKP or KEYLEN is overridden, it might not be possible to reconstruct the data 
set. 

The number of 80-byte logical records in an unloaded data set can be determined by 
the forrtiula: 

X = n(y+2) + 158 
78 

where x is the number of 80-byte logical records created, n is the number of records 
in the indexed sequential data set, and y is the length of a fixed record or the average 
length of variable records. 

Figure 32 shows the format of an unloaded data set for the first three 100-byte 
records of an indexed sequential data set. Each is preceded by two bytes (bb) that 
indicate the number of bytes in that record. (The last record is followed by two bytes 
containing binary zeros to identify the last logical record in the unloaded data set.) 
The characteristics of the indexed sequential data set are contained in the first two 
logical records of the unloaded data set. Data from the indexed sequential data set 
begins in the third logical record. Each logical record in the unioaded data set contains 
a binary sequence number (aa) in the first two bytes of the record. 



">" 80 bytes ■» 


a 
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b|b| Characteristics 


a 
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Cliaracteristics 


a 


a 


b|b| 76 bytes of data 


a 
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24 bytes of data |b|b| 52 bytes of data 
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a 


48 bytes of data |b|b| 28 bytes of data 


a 


a 


72 bytes of data |b|b| 



Figure 32. An Unloaded Data Set Created Using lEBISAIVI 



An indexed sequential data set can be created from an unloaded version of an 
indexed sequential data set. When the unloaded data set is loaded, those records 
that were contained in the overflow area assigned to the original indexed sequential 
data set are moved sequentially into the primary area of the loaded indexed 
sequential data set. 

The records of an indexed sequential data set can be printed or stored as a 
sequential data set for subsequent printing. Each input record is placed 
in a buffer from which it is printed or placed in a sequential data set. When the 
DELETE parameter is speciified in the OPTCD field, each input record not marked for 
deletion is also placed in a buffer from which it is printed or placed in a sequential 
data set. Each printed record is converted to hexadecimal unless specified otherwise 
by the user. 

lEBISAM provides user exits so that the user can include his own routines to: 

• IVIodify records before printing. 

• Select records for printing or terminate the printing operation after a certain 
number of records have been printed. 



• Convert the format of a record to be printed. 
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• Provide a record heading for each record if the record length is at least 18 bytes. If 
no user routines are provided, each record is identified in sequential order on the 
printout. 

When a user routine is supplied for a print operation, lEBISAM issues a LOAD macro 
instruction. A BALR 14,15 instruction is used to give control to the user's routine. 
When the user's routine receives control, register contains a pointer to a record 
heading buffer; register 1 contains a pointer to an input record buffer. 

The input record buffer has a length equal to the length of the input logical record. 

Figure 33 shows the record heading buffer. 
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-Total length = line length of applicable printer - 
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Input and Output 



Input record 



Total length = input logical record length (LRECL) 

Figure 33. Record Heading Buffer Used by lEBISAM 



Control 



The user returns control to lEBISAM by issuing a RETURN macro instruction (via 
register 14) or by using a BR 14 instruction after restoring registers 2 through 14. 
(Note that the user must save registers 2 through 14 when control is given to the user 
routine.) 

A user routine must place a return code in register 15 before returning control to 
lEBISAM. The possible return codes and their meanings are: 

o 00, which indicates that buffers are to be printed. 

• 04, which indicates that the buffers are to be printed and the operation is to be 
terminated. 

• 08, which indicates that this input record is not to be printed; processing continues. 

• 12, which indicates that this input record is not to be printed; terminate the 
operation. 

lEBISAM uses an input data set; the organization of the input data set depends on the 
operation to be performed, as follows: 

• If a data set is to be copied, unloaded, or printed in logical sequence, the input is 
an indexed sequential data set. 

• If a data set is to be loaded, the input is an unloaded sequential version of an 
indexed sequential data set. 

lEBISAM produces as output an output data set, which is the result of the lEBISAM 
operation, and a message data set, which contains informational messages and any 
error messages. 

lEBISAM provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

o 04, which indicates that a return code of 04 or 12 was passed to lEBISAM by the 
user routine. 

• 08, which indicates that an error condition occurred that caused termination of the 
operation. 

• 12, which indicates that a return code other than 00, 04, 08, or 12 was passed to 
lEBISAM from a user routine. The job step is terminated. 

• 16, which indicates that an error condition caused termination of the operation. 

lEBISAM is controlled by job control statements. Utility control statements are not 
used. 
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Job Control Statements Table 21 shows the job control statements necessary for using lEBISAM. 



Table 21. lEBISAM Job Control Statements 
Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGIVI = lEBISAM). Additional information is required 

on the EXEC statement to control the execution of lEBISAM; see "PARM 
Information on the EXEC Statement" below. 



SYSUTl DD Defines the input data set. 

SYSUT2 DD Defines the output data set. 

SYSPRINT DD Defines a sequential message data set, which can be written to a system output 
device, a tape volume, or a direct access device. 

The minimum region size that can be specified for the execution of lEBISAM is 8K. 

If the block size of the SYSPRINT data set is not a multiple of 121, a default value of 
121 is taken (no error message is issued, and no condition code is set). 

PARM Information on The PARM parameter on the EXEC statement is used to control the execution of 

the EXEC Statement lEBISAM. The PARM parameter is entered: 

PARM= {COPY } 

{ UNLOAD } 

{LOAD } 

{PRINTL } 

{*PRINTL[,N][,EXIT = routinename]' } 

The PARM values have the following meaning: 

• COPY specifies a copy operation. 

I • UNLOAD specifies an unload operation. This is the default. 

• LOAD specifies a load operation. 

• PRINTL specifies a print operation in which each record is converted to 
hexadecimal before printing. The N is an optional value that specifies that records 
are not to be converted to hexadecimal before printing. 

• EXIT is an optional value that specifies the name of an exit routine that is to receive 
control before each record is printed. 

Note: Exit routines must be included in either the job library or the link library. 

For a COPY operation, the SYSUT2 DD statement must include a primary space 
allocation that is sufficient to accommodate records that were contained in overflow 
areas in the original indexed sequential data set. New overflow areas can be specified 
when the data set is copied. 

For an UNLOAD operation, specifications that are implied by default or included in the 
DCB parameter of the SYSUT2 DD statement (for example, tape density) must be 
considered when the data set is subsequently loaded. If a block size is specified in the 
DCB parameter of the SYSUT2 DD statement, it must be a multiple of 80 bytes. 

For a LOAD operation, if the input data set resides on an unlabeled tape, the SYSUTl 
DD statement must specify a BLKSIZE that is a multiple of 80 bytes. Specifications 
that are implied by default or included in the DCB parameter of the SYSUTl DD 
statement must be consistent with specifications that were implied or included in the 
DCB parameter of the SYSUT2 DD statement used for the UNLOAD operation. The 
SYSUT2 DD statement must include a primary space allocation that is sufficient to 
accommodate records that were contained in overflow areas in the original indexed 
sequential data set. If new overflow areas are desired, they must be specified when 
the data set is loaded. 

For a PRINTL operation, if the device defined by the SYSUT2 DD statement is a 
printer, the specified BLKSIZE must be equal to or less than the physical printer size; 
that is 121, 133, or 145 bytes, if BLKSIZE is not specified, 121 bytes is assumed. 
LRECL (or BLKSIZE when no LRECL was specified) must be between 55 and 255 
bytes. 

If a user routine is supplied for a PRINTL operation, lEBISAM issues a LOAD macro 
instruction to make the user routine available. A BALR 14,15 instruction is 
subsequently used to give control to the routine. When the user routine receives 
control, register contains a pointer to a record heading buffer; register 1 contains a 
pointer to an input record buffer. 
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lEBISAM Examples 



The following examples Illustrate some of the uses of lEBISAM. Table 22 can be used 
as a quick reference guide to lEBISAM examples. The numbers in the "Example" 
column point to the examples that follow. 
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lEBISAM Example 2 



Table 22. 


lEBISAM Examp 


le Directory 






Operation 


Data Set 
Organization 


Devices 


Comments 


Example 


COPY 


indexed 
sequential 


2314 Disks 


Unblocked input; blocked output 
Prime area and index separation. 


1 


UNLOAD 


Indexed 

sequential. 

Sequential 


2314 Disk, 

9-track 

tape 


Blocked output. 


2 


UNLOAD 


Indexed 

sequential. 

Sequential 


2314 Disk, 

7-track 

tape 


Blocked output. Data set written 
as second data set on input 
volume. 


3 


LOAD 


Sequential, 

Indexed 

sequential 


9-track 
tape, 
2314 Disk 


Input data set is second data set 
on tape volume. 


4 


PRINTL 


Indexed 

sequential. 

Sequential 


2311 Disk, 

System 

Printer 


Blocked input. Output not 
converted. 


5 



In this example, an indexed sequential data set is to be copied from two 2314 
volumes to two other 2314 volumes. The output data is blocked. 

The example follows: 

//CPY JOB 09#770, SMITH 

// EXEC PGM=IEBISAM,PARM=COPY 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=ISAM01 ,VOLUME=SER=( 222222,333333 ), 

// DISP=( OLD, DELETE ),UNIT=( 2314,2 ), 
I // DCB=(DSORG=IS,RECFM=F,LRECL=500,RKP=4,BLKSIZE=500) 

//SYSUT2 DD DSNAME=ISAM02( INDEX ),UNIT=2314, 

// DISP= ( NEW , KEEP ) , V0LUME=SER=444444 , 
I // DCB=(DSORG=IS,RECFM=FB,BLKSIZE=1000),SPACE=(CYL,(2) ) 

// DD DSNAME=ISAM02 ( PRIME ),UNIT=( 2314,2 ), 

// DSB=( DSORG=IS , BLKSIZE=1 000 ) , SPACE=( CYL, (10)), 

// VOLUME=SER=( 444444,555555 ) ,DISP=( NEW, KEEP ) 

/* 

The control statements are discussed below: 

• EXEC specifies the program name and the COPY operation. 

• SYSUTl DD defines an indexed sequential input data set, which resides on two 
2314 volumes. 

• SYSUT2 DD defines the output data set index area; the index and prime areas are 
separated. 

I • The second SYSUT2 DD defines the output data set prime area. Ten cylinders are 
allocated for the prime area on each of the two 2314 volumes. 

In this example, indexed sequential input is to be converted into a sequential data set; 
the output is to be placed on a 9-track tape volume. 

The example follows: 

//STEP1 JOB 09#770, SMITH 
// EXEC PGM=IEBISAM,PARM=UNLOAD 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=INDSEQ,UNIT=2314,DISP=(OLD,KEEP), 
I // V0LUME=SER=1 1111 2 ,DCB=( DSORG=IS ) 

//SYSUT2 DD DSNAME=UNLDSET,UNIT=2400,LABEL=( ,SL), 

// DISP=( , KEEP ),VOLUME=SER=00 1234, 

// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=640 ) 

/* 

The control statements are discussed below: 

• EXEC specifies the program name and the UNLOAD operation. 

• SYSUTl DD defines the indexed sequential input data set, which resides on a 2314 
volume. 
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lEBISAM Example 3 



lEBISAM Example 4 



lEBISAM Example 5 



• SYSUT2 DD defines the unloaded output data set. The data set consists of fixed 
blocked records, and is to reside as the first or only data set on a 9-track tape 
volume. The data set is to be written at a density of 800 bits per inch. 

In this example, indexed sequential input is to be converted into a sequential data set 
and placed on a 7-track, tape volume. 

The example follows: 

//STEPA JOB 09#770, SMITH 
// EXEC PGM=IEBISAM,PARM=UNLOAD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INDSEQ,UNIT=2314,DISP=(OLD,KEEP), 
I // V0LUME=SER=1 1111 2 ,DCB=( DSORG=IS ) 
//SYSUT2 DD DSNAME=UNLDSET,UNIT=2400-2,LABEL=(2,SL), 
// VOLUME=SER=00 1 234 , DCB=( DEN=2 , RECFM=FB , 
// LRECL=80,BLKSIZE=1040,TRTCH=C),DISP=( ,KEEP) 
/* 

The control statements are discussed below: 

• EXEC specifies the program name and the UNLOAD operation. 

• SYSUTl DD defines the input data set, which is an indexed sequential data set. The 
data set resides on a 2314 volume. 

• SYSUT2 DD defines the unloaded output data set. The data set consists of fixed 
blocked records, and is to reside as the second data set on a 7-track tape volume. 
The data set is to be written at 800 bits per inch density. 

In this example, an unloaded data set is to be converted to the form of the original 
indexed sequential data set. 

The example follows: 

//STEPA JOB 09#770, SMITH 

// EXEC PGM=IEBISAM,PARM=LOAD 

//SYSPRINT DD SYSOUT^A 

//SYSUTl DD DSNAME=UNLDSET,UNIT=2400,LABEL=( 2,SL), 

// DISP=(OLD,KEEP),VOLUME=SER=001234 

//SYSUT2 DD DSNAME=INDSEQ,DISP=( ,KEEP),DCB=(DSORG=IS ), 

// SPACE=(CYL,( 1 ) ),V0LUME=SER=1 1 11 12,UNIT=2314 

/* 

The control statements are discussed below: 

• EXEC specifies the program name and the LOAD operation. 

• SYSUTl DD defines the input data set, which is a sequential (unloaded) data set. 
The data set is the second data set on a 9-track tape volume. 

• SYSUT2 DD defines the output data set, which is an indexed sequential data set. 
One cylinder of space is allocated for the data set on a 2314 volume. 

In this example, the logical records of an indexed sequential data set are to be printed 
on a system output device. 

The example follows: 

//PRINT JOB 09#770, SMITH 

// EXEC PGM=IEBISAM,PARM='PRINTL,N' 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=ISAM03,UNIT=231 1 ,DISP=OLD, 
I // VOLUME=SER=222222,DCB=(DSORG=IS ) 

//SYSUT2 DD SYSOUT=A 
/* 

The control statements are discussed below: 

• EXEC specifies the program name and the PRINTL operation. The output records 
are not to be converted to hexadecimal prior to printing. 

• SYSUTl DD defines the input data set, which resides on a 2311 volume. 

• SYSUT2 DD defines the output data set. A logical record length (LRECL) of 121 
bytes is assumed. 
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Printing or Punching 
a Data Set 



Printing or Punching 
Selected Members 

Printing or Punching 
Selected Records 



Printing or Punching 
a Partitioned Directory 



lEBPTPCH is a data set utility used to print or punch all, or selected portions, of a 
sequential or partitioned data set. Records can be printed or punched to meet either 
standard specifications or user specifications. (See "Introduction" for general data set 
utility information.) 

The standard specifications are: 

• Each logical record begins on a new printed line or punched card. 

• Each printed line consists of groups of 8 characters separated by 2 blanks. Each 
punched card contains up to 80 contiguous bytes of information. 

• Characters that cannot be printed appear as blanks. 

• When the input is blocked, each logical record is delimited by "*" and each block is 
delimited by "**". 

User formats can be specified, provided that no output record exceeds the capability 
of the output device. 

lEBPTPCH provides optional editing facilities and exits for user routines that can be 
used to process labels or manipulate input or output records. 

lEBPTPCH can be used to: 

• Print or punch a sequential or partitioned data set in its entirety. 

• Print or punch selected members from a partitioned data set. 

• Print or punch selected records from a sequential or partitioned data set. 

• Print or punch the directory of a partitioned data set. 

• Print or punch an edited version of a sequential or partitioned data set. 

At the completion or termination of the program, the highest return code encountered 
within the program is passed to the calling program. 

lEBPTPCH can be used to print or punch a sequential data set or a partitioned data 
set in its entirety. Data to be printed or punched can be either hexadecimal or a 
character representation of valid alphameric bit configurations. For a print operation, 
packed decimal data should be converted to unpacked decimal or hexadecimal mode 
to ensure that all characters are printable. 

For a standard print operation, each logical record is printed in groups of eight 
characters. Each set of eight characters is separated from the next by two blanks. Up 
I to 112 characters can be included on a printed line. (An edited output can be 
produced to omit the blank delimiters and print up to 144 characters per line.) 

Data from an input logical record is punched in contiguous columns in the punched 
card(s) representing that record. Sequence numbers can be created and placed in 
columns 73 through 80 of the punched cards. 

lEBPTPCH can be used to print or punch selected members of a partitioned data set. 
Utility control statements are used to specify members to be printed or punched. 

lEBPTPCH can be used to print selected records from a sequential or partitioned 
data set. Utility control statements can be used to specify: 

• The termination of a print or punch operation after a specified number of records 
has been printed or punched. 

• The printing or punching of every nth record. 

I • The starting of a print or punch operation after a specified number of records. 

lEBPTPCH can be used to print or punch the contents of a partitioned directory. 
Each directory block is printed in groups of eight characters. If the directory is printed 
in hexadecimal representation, the first four printed characters of each directory block 
indicate the total number of used bytes in that block. For details of the format of the 
directory, see OS System Control Blocks, GC28-6628. 

Data from a directory block is punched in contiguous columns in the punched cards 
representing that block. 
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Printing or Punching 
an Edited Data Set 



Input and Output 



Control 



Job Control Statements 



lEBPTPCH can be used to print or punch an edited version of a sequential or a 
partitioned data set. Utility control statements can be used to specify editing 
information that applies to a record, a group of records, selected groups of records, 
or an entire member or data set. 

An edited data set is produced by: 

• Rearranging or omitting defined data fields within a record. 

• Converting data from packed decimal to unpacked decimal or from alphameric to 
hexadecimal representation. 

lEBPTPCH uses the following input: 

• An input data set, which contains the data that is to be printed or punched. The 
input data set can be either sequential or partitioned. 

• A control data set, which contains utility control statements. The control data set is 
required for each use of lEBPTPCH. 

lEBPTPCH produces the following output: 

• An output data set, which is the printed or punched data set. 

• A message data set, which contains informational messages (for example, the 
contents of the control statements) and any error messages. 

lEBPTPCH provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates either that a physical sequential data set is empty, or that a 
partitioned data set contains no members. 

• 08, which indicates that a member specified for printing does not exist in the input 
data set. Processing continues with the next member. 

• 12, which indicates that an unrecoverable error occurred or that a user routine 
passed a return code of 12 to lEBPTPCH. The job step is terminated. 

• 16, which indicates that a user routine passed a return code of 16 to lEBPTPCH. 
The job step is terminated. 

lEBPTPCH is controlled by job control statements and utility control statements. The 
job control statements are required to execute or invoke the lEBPTPCH program and 
to define the data sets that are used and produced by the program. The utility control 
statements are used to control the functions of lEBPTPCH. 

Table 23 shows the job control statements necessary for using lEBPTPCH. 

Table 23. lEBPTPCH Job Control Statements 

Statement Use 

JOB Initiates the job step. 

EXEC Specifies the program name (PGM = lEBPTPCH) or, if the job control statements 

reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a system 
output device, a tape volume, or a direct access device. 

SYSUTl DD Defines a sequential or partitioned input data set. 

SYSUT2 DD Defines the output (printed or punched) data set. 

SYSIN DD Defines the control data set. The control data set normally resides in the input 

stream; however, it can be defined as a member in a partitioned data set. 

The minimum region size that can be specified for the execution of lEBPTPCH is 
I6K + 2b, where b is the largest block size in the job step rounded to the next higher 
2K. 

The input data set can contain fixed, variable, undefined, or variable spanned records. 
Variable spanned records are allowed only when the input is sequential. 

Both the output data set and the message data set can be written to the system 
output device if it is a printer. Variable spanned records are allowed only when the 
input is sequential. 
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Restrictions 



Utility Control Statements 



If the logical record length of the input records is such that the output would exceed 
the output record length, the utility divides the record into multiple lines or cards in 
the case of standard printed output, standard punched output, or when the PREFORM 
parameter was specified. Otherwise, only part of the input record is printed (a 
maximum of 144 characters) or punched (a maximum of 80 characters). 

• The SYSPRINT DD statement is required for each use of lEBPTPCH. 

• The RECFM must be fixed block with ASCII carriage control characters (FBA), and 
the LRECL must be 121. Output can be blocked by specifying a BLKSIZE which is a 
multiple of 121 on the SYSPRINT DD statement. The default BLKSIZE is 121. 

• The SYSUTl DD statement is required for each use of lEBPTPCH. The RECFM 
(except for undefined records), and the BLKSIZE and the LRECL (except for 
undefined and fixed unblocked records) must be present on the DD statement, in 
the DSCB, or on the tape label. 

• The SYSUT2 DD statement is required for each use of lEBPTPCH. The RECFM must 
be FBA or fixed block with machine-code control characters (FBM). 

• The LRECL parameter, or, if no logical record length is specified, the BLKSIZE 
parameter, specifies the number of characters to be written per printed line or per 
punched card (this count includes a control character). The number of characters 
specified must be in the range of 2 through 145. The default values for edited 
output lines are 121 characters per printed line and 81 characters per punched 
card. The SYSUT2 data set can be blocked by specifying both the LRECL and the 
BLKSIZE parameters, in which case, block size must be a multiple of logical record 
length. 

• The block size for the SYSPRINT data set must be a multiple of 121. The block size 
for the SYSIN data set must be a multiple of 80. Any blocking factor can be 
specified for these block sizes. 

• The SYSIN DD statement is required for each use of lEBPTPCH. 

• The RECFM must be FB and the LRECL must be 80. Any blocking factor can be 
specified for the BLKSIZE (multiple of 80). The default BLKSIZE is 80. 

• A partitioned directory to be printed/punched must be defined as a sequential data 
set (TYPORG = PS). Code the RECFM, BLKSIZE, and LRECL in the SYSUTl DD 
card. 

lEBPTPCH is controlled by utility control statements. The control statements are 
shown in the order in which they must appear, as follows: 

• PRINT or PUNCH statement, which specifies that the data is to be either printed or 
punched. 

• TITLE statement, which specifies that a title is to precede the printed or punched 
data. 

• EXITS statement, which specifies that user routines are provided. 

• MEMBER statement, which specifies that the input is a partitioned data set and that 
a selected member is to be printed or punched. 

• RECORD statement, which specifies whether editing is to be performed, that is, 
records are to be printed or punched to nonstandard specifications. 

• LABELS statement, which specifies whether user labels are to be treated as data. 

The control statements are included in the control data set, as required. Any number 
of MEMBER and RECORD statements can be included in a job step. 
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PRINT Statement 



The PRINT statement is used to initiate tlie lEBPTPCH operation. If this is a print 
operation, PRINT must be the first statement in the control data set. 

The format of the PRINT statement is: 

i"[/aibe/] PRINT [PREFORM = {A} 

{M}] 

[,TYPORG= {PS} 
1 {PO}] 

[JOTCONV = {)CE ) 
{PZ }] 

[.CNTRL = n] 

[,STRTAFT = n] 

[.STOPAFT = n] 

[,SKIP = n] 

[.MAXNAME = n] 
j [,MAXFLDS = n] 

I [.MAXGPS = n] ' 

[.MAXLITS = n] 

[,INITPG = n] 

[,MAXLINE = n] 
where: 

PREFORM = 

specifies that a control character is provided as the first character of each record 
to be printed. The control characters are used to control the spacing, number of 
lines per page, and page ejection. If an error occurs, the print operation is 
terminated. If PREFORM is coded, except for syntax checking, any additional PRINT 
operands and all other control statements except LABELS statements are ignored. 
PREFORM must not be used for printing data sets with VS or VBS records longer 
than 32K bytes. These values can be coded: 



M 



specifies that an ASA control character is provided as the first character of each 
record to be printed. If the input record length exceeds the output record 
length, the utility uses the ASA character for printing the first line, with a single 
space character on all subsequent lines of the record. 

specifies that a machine-code control character is provided as the first 
character of each record to be printed. If the input record length exceeds the 
output record length, the utility prints all lines of the record with a 
print-skip-one-line character until the last line of the record, which will contain 
the actual character provided as input. 

TYPORG = 

specifies the organization of the input data set. If TYPORG is omitted, sequential 
organization is assumed. These values can be coded: 



PS 



specifies that the input data set is organized sequentially. 

PO 

specifies that the input data set is partitioned. 

TOTCONV = 

specifies the representation of data to be printed. TOTCONV can be overridden by 
any user specifications (RECORD statements) that pertain to the same data. These 
values can be coded: 



XE 



PZ 



specifies that data is to be printed in 2-character per byte hexadecimal 
representation (for example, 03 40 F4 F6). If XE is not specified, data is printed 
in 1-character per byte alphameric representation. The above example would 
appear as C 46. 

specifies that data (packed decimal mode) is to be converted to unpacked 
decimal mode. If TOTCONV is omitted, data is not converted. lEBPTPCH does 
not check for packed decimal mode. The output is unpredictable when the input 
is not packed decimal. 
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CNTRL = n 

specifies a control character for the output device that indicates line spacing, as 
follows: 1 indicates single spacing; 2 indicates double spacing; and 3 indicates 
triple spacing. If CNTRL is omitted, 1 is assumed. 

STRTAFT = n 

specifies, for sequential data sets, the number of logical records (physical blocks in 
the case of VS or VBS type records longer than 32K bytes) to be skipped before 

I printing begins. For partitioned data sets, specifies the number of logical records to 
be skipped in each member before printing begins. The n value must not exceed 
32,767. If STRTAFT is specified and RECORD statements are present, the first 
RECORD statement of a member describes the format of the first logical record to 
be printed. 

STOPAFT = n 

specifies, for sequential data sets, the number of logical records (or physical blocks 
in the case of VS or VBS records longer than 32K bytes) to be printed. For 

(partitioned data sets, this specifies the number of logical records to be printed in 
each member to be processed. The n value must not exceed 32,767. If STOPAFT is 
specified and RECORD statements are present, the operation is terminated when 

I the STOPAFT count is satisfied, at the end of a record group, or at the end of the 
data set; whichever occurs first. 

SKIP = n 

specifies that every nth record (or physical block in the case of VS or VBS records 
longer than 32K bytes) is to be printed. If SKIP is omitted, successive logical 
records are printed. 

MAXNAME = n 

specifies a number no less than the total number of subsequent MEMBER 
statements. If MAXNAME is omitted when there is a MEMBER statement present, 
the print request is terminated. 

MAXFLDS = n 

specifies a number no less than the total number of FIELD parameters appearing in 
I subsequent RECORD statements. If MAXFLDS is omitted when there is a FIELD 
parameter present, the print request is terminated. 

MAXGPS = n 

specifies a number no less than the total number of IDENT parameters appearing in 
subsequent RECORD statements. If MAXGPS is omitted when there is an IDENT 
parameter present, the print request is terminated. 

MAXLITS = n 

specifies a number no less than the total number of characters contained in the 
IDENT literals of subsequent RECORD statements. If MAXLITS is omitted when 
there is a literal present, the print request is terminated. 

INITPG = n 

specifies the initial page number; the pages are numbered sequentially thereafter. 
I If INITPG is omitted, 1 is assumed. The value of n must not be greater than 9999. 

MAXLINE = n 

specifies the maximum number of lines to a printed page. Spaces, titles, and 
subtitles are included in this number. If n is smaller than the total number of 
spaces, titles, and subtitles, an error message is issued. If MAXLINE is omitted, 60 
is assumed. 
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PUNCH Statement The PUNCH statement is used to initiate the lEBPTPCH operation. If this is a punch 

operation, PUNCH must be the first statement in the control data set. 

The format of the PUNCH statement is: 

' [lat)eli] PUNCH [ PREFORM = {A } 

{M }] 

[,TYPORG= {PS} 
{PO}] 

[JOTCONV = {XE } 
{PZ}] 

[.CNTRL = n] 

[.STRTAFT = n] 

[.STOPAFT = n] 

[.SKIP = n] 
; [.MAXNAME = n] 

[,MAXFLDS = n] 

[.MAXGPS = n] 

[.MAXLITS = n] 

[,CDSEQ = n] 

[.CDINCR = n] 
where: 

PREFORM = 

specifies that a control character is provided as the first character of each record 
to be punched. The control characters are used to select a stacker. If an error is 
discovered, the punch operation is terminated. If PREFORM is coded, except for 
syntax checking, any additional PUNCH operands and all other control statements 
except LABELS statements are ignored. PREFORM must not be used for punching 
data sets with VS or VBS records longer than 32K bytes. These values can be 
coded: 

A 

specifies that an ASA control character is provided as the first character of each 
record to be punched. If the input record length exceeds the output record 
length, the utility duplicates the ASA character on each output card of the 
record. 

M 

specifies that a machine-code control character is provided as the first 
character of each record to be punched. If the input record length exceeds the 
output record length, the utility duplicates the machine control character on 
each output card of the record. 

TYPORG = 

specifies the organization of the input data set. If TYPORG is omitted, sequential 
organization is assumed. These values can be coded: 

PS 

I specifies that the input data set is organized sequentially. This is the default. 

PO 

specifies that the input data set is partitioned. 

TOTCONV = 

specifies the representation of data to be punched. TOTCONV can be overridden by 
any user specifications (RECORD statements) that pertain to the same data. These 
values can be coded: 

XE 

specifies that data is to be punched in 2-character per byte hexadecimal 
representation (for example, C3 40 F4 F6). If XE is not specified, data is 
punched in 1 -character per byte alphameric representation. The above example 
would appear as C 46. 

PZ 

specifies that data (packed decimal mode) is to be converted to unpacked 

I decimal mode. If TOTCONV is omitted, data is not converted. lEBPTPCH does 

not check for packed decimal mode. The output is unpredictable when the input 
is not packed decimal. 
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CNTRL = n 

specifies a control character for the output device that is used to select the 
stacker, as follows: 1 indicates the first stacker and 2 indicates the second stacker. 
If CNTRL is omitted, 1 is assumed. 

STRTAFT = n 

specifies, for sequential data sets, the number of logical records (physical blocks in 
the case of VS or VBS type records longer than 32K bytes) to be skipped before 
punching begins. For partitioned data sets, specifies the number of logical records 
(physical blocks in the case of VS or VBS type records longer than 32K bytes) to be 
skipped in each member before punching begins. The n value must not exceed 
32,767. If STRTAFT is specified and RECORD statements are present, the first 
RECORD statements of a member describes the format of the first logical record to 
be punched. 

STOPAFT = n 

specifies, for sequential data sets, the number of logical records (or physical blocks 
in the case of VS or VBS records longer than 32K bytes) to be punched. For 
partitioned data sets, this specifies the number of logical records (or physical 
blocks in the case of VS or VBS records longer than 32K bytes) to be punched in 
each member to be processed. The n value must not exceed 32,767. If STOPAFT is 
specified and RECORD statements are present, the operation is terminated when 
the STOPAFT count is satisfied or at the end of the first record group, whichever 
occurs first. 

SKIP = n 

specifies that every nth record (or physical block in the case of VS or VBS records 
longer than 32K bytes) is to be punched. If SKIP is omitted, successive logical 
records are punched. 

MAXNAME = n 

specifies a number no less than the total number of subsequent MEMBER 
statements. If MAXNAME is omitted when there is a MEMBER statement present, 
the punch request is terminated. 

MAXFLDS = n 

specifies a number no less than the total number of FIELD parameters appearing in 
subsequent RECORD statements. If MAXFLDS is omitted when there is a FIELD 
parameter present, the punch request is terminated. 

MAXGPS = n 

specifies a number no less than the total number of IDENT parameters appearing in 
subsequent RECORD statements. If MAXGPS is omitted when there is an IDENT 
parameter present, the punch request is terminated. 

MAXLITS = n 

specifies a number no less than the total number of characters contained in the 
IDENT literals of subsequent RECORD statements. If MAXLITS is omitted when 
there is a literal present, the punch request is terminated. 

CDSEQ = n 

specifies the initial sequence number of a deck of punched cards. This value must 
be contained in columns 73 through 80. Sequence numbering Is initialized for each 
member of a partitioned data set. If CDSEQ is omitted, the cards are not numbered. 
If the value of n is zero, 00000000 is assumed as a starting sequence. 

CDINCR = n 

specifies the increment to be used in generating sequence numbers. If CDINCR is 
omitted and CDSEQ is coded, 10 is assumed as an increment value for sequence 
numbering. 

TITLE Statement The TITLE statement is used to request title and subtitle records. Two TITLE 

statements can be included for each use of lEBPTPCH. A first TITLE statement defines 
the title, and a second defines the subtitle. The TITLE statement, if included, must 
immediately follow the PRINT or PUNCH statement in the control data set. 

The format of the TITLE statement is: 

[name] TITLE ITEM = (•m/e'[,output-/ocaf/on])[,ITEM...] 
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EXITS Statement 



MEMBER Statement 



RECORD Statement 



where: 

ITEM = 

specifies title or subtitle information. The values that can be coded are: 

'title' 

specifies the title or subtitle literal (maximum length of 40 bytes), enclosed in 
apostrophes. If the literal contains apostrophes, each apostrophe must be 
written as two consecutive apostrophes. 

output -location 

specifies the starting position at which the literal for this item is to be placed in 
the output record. If output-location is not specified, 1 is assumed. The specified 
title may not exceed the output logical record length minus 1. 

The EXITS statement is used to identify exit routines supplied by the user. Exits to 
label processing routines are ignored if the input data set is partitioned. Linkage to 
and from user routines are discussed in "Appendix A: Exit Routine Linkage." 

The EXITS statement, if included, must immediately follow any TITLE statement or 
follow the PRINT or PUNCH statement. 

The format of the EXITS statement is: 

[/aba/] EXITS [INHDR = rout/nename] 
[INTLR = rout/nename] 
[INREC = routinename] 
[OUTREC = routinename] 
where: 

INHDR = routinename 

specifies the symbolic name of a routine that processes user input header labels. 

INTLR = routinename 

specifies the symbolic name of a routine that processes user input trailer labels. 

INREC = routinename 

specifies the symbolic name of a routine that manipulates each logical record (or 
physical block in the case of VS or VBS records longer than 32K bytes) before it is 
processed. 

OUTREC = routinename 

specifies the symbolic name of a routine that manipulates each logical record (or 
physical block in the case of VS or VBS records longer than 32K bytes) before it is 
printed or punched. When standard specifications are used, this exit is not 
available. 

The MEMBER statement is used to identify members to be printed or punched. All 
RECORD statements that follow a MEMBER statement pertain to the member indicated 
in that MEMBER statement only. When RECORD and MEMBER statements are used, at 
least one MEMBER statement must precede the first RECORD statement. If no 
RECORD statement is used, the member is processed to standard specifications. 

If no MEMBER statement appears, and a partitioned data set is being processed, all 
members of the data set are printed or punched. Any number of MEMBER statements 
can be included in a job step. 

The format of the MEMBER statement is: 



[label] MEMBER NAME = 



{membername } 
{aliasname } 



where: 



NAME = 

specifies a member to be printed or punched. These values can be coded: 

membername 

specifies a member by its member name. 

aliasname 

specifies a member by its alias. 

If the NAME parameter is specified in the MEMBER statement, MAXNAME must be 
specified in a PRINT or PUNCH statement. 

The RECORD statement is used to define a group of records — called a record 
group — that is to be printed or punched to the user's specifications. A record group 
consists of any number of records to be edited identically. 
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If no RECORD statements appear, the entire data set, or named member, is printed or 
punched to standard specifications. If a RECORD statement is used, all data following 
the record group it defines (within a partitioned member or within an entire sequential 
data set) must be defined with other RECORD statements. Any number of RECORD 
statements can be included in a job step. 

The format of the RECORD statement is: 



[label] RECORD [IDENT = (length,'name\input-location)} 

[,FIELD = (length[,input-location][,conversion] 
[ [,output-/ocat/on])] [.FIELD = ...] j 

where: 

IDENT = 

identifies the last record of the record group to which the FIELD parameters apply. 
If IDENT is omitted and STOPAFT is not included with the PRINT or PUNCH 
statement, record processing halts after the last record in the data set. If IDENT is 
omitted and STOPAFT Is included with the PRINT or PUNCH statement, record 
processing halts when the STOPAFT count is satisfied or after the last record of the 
data set is processed, whichever occurs first. The values that can be coded are: 

length 

specifies the length (in bytes) of the field that contains the identifying name in 
the input records. The length cannot exceed eight bytes. 

'name' 

specifies the exact literal that identifies the last record of a record group. If the 
literal contains apostrophes, each must be written as two consecutive 
apostrophes. 

input-location 

specifies the starting location of the field that contains the identifying name in 
the input records. 

Note: The sum of the length and input location must be equal to or less than the 
initial LRECL plus one. 

FIELD = 

specifies field processing and editing information. These values can be coded: 

length 

specifies the length (in bytes) of the input field to be processed. 

I Note: The length must be equal to or less than the initial input LRECL. 

input-location 

specifies the starting byte of the input field to be processed. If input-location is 
not specified, 1 is assumed. 

I Note: The sum of the length and input location must be equal to or less than the 
initial input LRECL plus one. 

conversion 

specifies a two-byte code that indicates the type of conversion to be performed 
on this field before it is printed or punched. If conversion is not specified, the 
field is moved to the output area without change. The values that can be coded 
are: 

PZ 

specifies that data (packed decimal) is to be converted to unpacked decimal 
data. The converted part of the input record (length L) occupies 2L - 1 output 
characters. 

XE 

specifies that data (alphameric) is to be converted to hexadecimal data. The 
converted part of the input record (length L) occupies 2L output characters. 

output-/ocat;on 

specifies the starting location of this field in the output records. If output-location 
is not specified, 1 is assumed. Unspecified fields in the output records appear as 
blanks in the printed or punched output. Data that exceeds the SYSUT2 printer 
or punch size is not printed or punched. The specified fields may not exceed the 
output logical record length minus 1. When either one or multiple "FIELDS" are 
specified, the sum of all lengths and extra characters needed for conversions 
must be equal to or less than the output LRECL minus one. 



lEBPTPCH Program -Class C 137 



LABELS Statement 



A RECORD statement referring to a partitioned data set for which no members have 
been named need contain only FIELD parameters. These are applied to the records in 
all members of the data set. 

If a FIELD parameter is included in the RECORD statement, MAXFLDS must be 
specified in the PRINT/PUNCH statement. 

If an IDENT parameter is included in the RECORD statement, MAXGPS must be 
specified in the PRINT/PUNCH statement. If a literal is specified in the IDENT 
parameter, MAXLITS must be specified in the PRINT/PUNCH statement. 

The LABELS statement specifies whether user labels are to be treated as data. For a 
detailed discussion of this option, refer to "Processing User Labels as Data," in 
"Appendix E: Processing User Labels." 

The format of the LABELS statement is: 

[name] LABELS [DATA = {YES } 
{NO } 
{ALL } 
{ONLY }] 

where: 

DATA = 

specifies whether user labels are to be treated as data. The values that can be 
coded are: 



YES 



specifies that any user labels that are not rejected by a user's label processing 
routine are to be treated as data. Processing of labels as data stops in 
compliance with standard return codes. If no value is entered, YES is assumed. 



NO 



specifies that user labels are not to be treated as data. 



ALL 



specifies that user labels are to be treated as data regardless of any return 
code. A return code of 16 causes the utility to complete the processing of the 
remainder of the group of user labels and to terminate the job step. 

ONLY 

specifies that only user header labels are to be treated as data. User header 
labels are processed as data regardless of any return code. The job terminates 
upon return from the OPEN routine. 

Note: DATA = NO must be specified to make standard user labels (SUL) exits inactive 
when input data sets with nonstandard labels (NSL) are to be processed. 

If more than one valid LABELS statement is included, all but the last LABELS 
statement are ignored. 
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lEBPTPCH Examples 



The following examples illustrate some of the uses of lEBPTPCH. Table 24 can be 
used as a quick reference guide to lEBPTPCH examples. The numbers in the 
"Example" column point to the examples that follow. 



Table 24. lEBPTPCH Example Directory 



lEBPTPCH Example 1 



Operation 



Data Set 
Organization 



PRINT Sequential 

PUNCH Sequential 

PRINT Partitioned 

PRINT Partitioned 

PRINT Sequential 

PUNCH Sequential 



PRINT Sequential, 

Partitioned 

PUNCH Sequential 



PRINT Sequential 



Devices 

9-track tape, 
System printer 

7-track tape. 
Card Reader 



Comments 

Standard format. Conversion to 
hexadecimal. 

Standard format. Conversion to 
hexadecimal. 



Example 
1 
2 



3330 Disk Storage Standard format. Conversion to 

System printer hexadecimal. Ten records from 

each member are to be printed. 

2314 Disk, Standard format. Conversion to 

System printer hexadecimal. Two members are 

to be printed. 

9 track tape, User specified format. Input 

System printer data set is the second data set 
on the volume. 

2314 Disk, User specified format. Sequence 

Card Reader numbers are to be assigned and 

Punch punched. 

2314 Disk, Standard format. Conversion to 

System printer hexadecimal. 

Card Reader, Standard format. Control data 

Card Read set is a member in a cataloged 

Punch partitioned data set. 

2311 Disk, User specified format. User 

System printer routines are provided. Processing 

ends after first record group is 

printed. 



In this example, a sequential data set is to be printed according to standard 
specifications. The input data set resides on a 9-track tape volume, originally written 
at 800 bits per inch density. The printed output is to be converted to hexadecimal. 

The example follows: 

//PRINT JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2400,LABEL=( ,NL),VOLUME=SER=001234, 

// DISP=( OLD, KEEP ),DCB=(RECFM=U,BLKSIZE=2000) 

//SYSUT2 DD SYSOUT=A 

//SYSIN DD * 

PRINT TOTCONV=XE 

TITLE ITEM=( 'PRINT SEQ DATA SET WITH CONV TO HEX ' , 1 ) 
/* 

The control statements are discussed below. 

• SYSUTl DD defines the input data set. The data set contains undefined records; no 
record is larger than 2,000 bytes. 

• SYSUT2 DD defines the output data set. The data set is written to the system 
output device (printer assumed). Each printed line contains groups (8 characters 
each) of hexadecimal information. Each record begins a new line of printed output. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT and TITLE statements. 

• PRINT initiates the print operation and specifies conversion from alphameric to 
hexadecimal representation. 

o TITLE specifies a title to be placed beginning in column 10 of the printed output. 
The title is not converted to hexadecimal. 
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lEBPTPCH Example 2 



lEBPTPCH Example 3 



In this example, a sequential data set is to be punched according to standard 
specifications. The input data set resides on a 7-track tape volume, originally written 
at a density of 556 bits per inch. The punched output is converted to hexadecimal. 

The example follows: 

//PUNCHSET JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=INSET,UNIT=2400-2,VOLUME=SER=001234, 

// LABEL=( , NL),DISP=( OLD, KEEP ), DCB= ( DEN= 1 ,RECFM=FB, 

// LRECL=80,BLCKSIZE=2000,TRTCH=C) 

//SYSUT2 DD UNIT=2540-2 

//SYSIN DD * 

PUNCH TOTCONV=XE 

TITLE ITEM=( 'PUNCH SEQ DATA SET WITH CONV TO HEX ',10) 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set contains 80-byte, fixed 
blocked records. 

• SYSUT2 DD defines the output data set. The data set is to be punched by an IBM 
2540-2 Card Read Punch (punch feed). Each record from the input data set is 
represented by two punched cards. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PUNCH and TITLE statements. 

• PUNCH initiates the punch operation and specifies conversion from alphameric to 
hexadecimal representation. 

• TITLE specifies a title to be placed beginning in column 10. The title is not 
converted to hexadecimal. 

In this example, a partitioned data set (ten records from each member) is to be 
printed according to standard specifications. The input data set resides on a 3330 
volume. The printed output is converted to hexadecimal. 

The example follows: 

//PRINTPDS JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=PDS,UNIT=3330,DISP=( OLD, KEEP), 

// V0LUME=SER=1 1 1 1 1 2 ,DCB=( RECFM=U, BLKSIZE=3265 ) 

//SYSUT2 DD SYSOUT=A 

//SYSIN DD * 

PRINT TOTCONV=XE , TYPORG=PO , STOPAFT= 1 

TITLE ITEM=( 'PRINT PDS - 10 RECS EACH MEM', 20) 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set contains undefined records; no 
record is larger than 3,625 bytes. 

• SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains groups (8 characters each) of hexadecimal 
information. Each record begins a new line of printed output. The size of the record 
determines how many lines of printed output are required per record. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT and TITLE statements. 

• PRINT initiates the print operation, specifies conversion from alphameric to 
hexadecimal representation, indicates that the input data set is partitioned, and 
specifies that ten records from each member are to be printed. 

• TITLE specifies a title to be placed beginning in column 20 of the printed output. 
The title is not converted to hexadecimal. 



140 Utilities (Release 21.7) 



lEBPTPCH Example 4 



lEBPTPCH Example 5 



In this example, two partitioned members are to be printed according to standard 
specifications. The input data set resides on a 2314 volume. The printed output is to 
be converted to hexadecimal. 

The example follows: 

//PRNTMEMS JOB 09#660, SMITH 
// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDS,DISP=(0LD,KEEP),V0LUME=SER=111 112, 
// DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) , UNIT=23 1 4 
//SYSUT2 DD SYSOUT=A 
* 

TYPORG=PO , TOTCONV=XE , MAXNAME=2 

ITEM=( 'PRINT TWO MEMBS WITH CONV TO HEX ',10) 

NAME=MEMBER1 

NAME=MEMBER2 



//SYSIN DD 

PRINT 

TITLE 

MEMBER 

MEMBER 

/* 

The control statements are discussed below: 



• SYSUTl DD defines the input data set. The data set contains 80-byte, fixed 
records. 

o SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains groups (8 characters each) of hexadecimal 
information. Each record begins a new line of printed output. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains PRINT, TITLE, and MEMBER statements. 

• PRINT initiates the print operation, indicates that the input data set is partitioned, 
specifies conversion from alphameric to hexadecimal representation, and indicates 
that two MEMBER statements appear in the control data set. 

• TITLE specifies a title to be placed beginning in column 10 of the printed output. 
The title is not converted to hexadecimal. 

o MEMBER specifies the member names of the members to be printed. 

In this example, a sequential data set is to be printed according to user specifications. 
The input data set is the second data set on a 9-track tape volume. The data set was 
originally written at a density of 800 bits per inch. 

The example follows: 

//PTNONSTD JOB 09#660, SMITH 
// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=SEQSET,UNIT=2400,LABEL=( 2,SUL), 
// DISP=( OLD, KEEP ) , VOLUME=SER=001 234 , 
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 
//SYSUT2 DD SYSOUT=A 
* 

MAXFLDS=1 

INHDR=HDRIN, INTLR=TRLIN 

FIELD=(80 ) 

DATA=YES 



//SYSIN DD 

PRINT 

EXITS 

RECORD 

LABELS 

/* 

The control statements are discussed below: 



SYSUTl DD defines the input data set. The data set contains 80 byte, 
fixed blocked records. 

SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains 80 contiguous characters (one record) of 
information. 

SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT, RECORD, EXITS and LABELS statements. 

PRINT initiates the print operation and indicates that one FIELD parameter is 
included in a subsequent RECORD statement. 

EXITS indicates that exits will be taken to user header label and trailer label 
processing routines when these labels are encountered on the SYSUTl data set. 

RECORD indicates that each input record is to be processed in its entirety (80 
bytes). Each input record is printed in columns 1 through 80 on the printer. 

LABELS specifies that user header and trailer labels are to be printed according to 
the return code issued by the user exits. 
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lEBPTPCH Example 6 



lEBPTPCH Example 7 



In this example, a sequential data set is to be punched according to user 
specifications. The input data set resides on a 2314 volume. 

The example follows: 

//PHSEQNO JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=SEQSET,UNIT=2314,LABEL=( ,SUL), 

// V0LUME=SER=1 1111 2 ,DISP=( OLD,KEEP ) , 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 

//SYSUT2 DD DSNAME=PUNCHSET,UNIT=2540-2 

* 

MAXFLDS=1 ,CDSEQ=00000000,CDINCR=20 

FIELD=( 72 ) 

DATA=YES 



//SYSIN DD 
PUNCH 

RECORD 

LABELS 
/* 

The control statements are discussed below: 



• SYSUTl DD defines the input data set. The data set contains 80-byte, fixed 
blocked records. 

• SYSUT2 DD defines the output data set. The data set is to be punched by an IBM 
2540-2 Card Read Punch (punch feed). Each record from the input data set is 
represented by one punched card. 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control, data set contains the PUNCH, RECORD, and LABELS statements. 

• PUNCH initiates the punch operation, indicates that one FIELD parameter is 
included in a subsequent RECORD statement, and assigns a sequence number for 
the first punched card (00000000) and an increment value for successive 
sequence numbers (20). Sequence numbers are placed in columns 73 through 80 
of the output records. 

• RECORD indicates that bytes 1 through 72 of the input records are to be punched. 
Bytes 73 through 80 of the input records are replaced by the new sequence 
numbers in the output card deck. 

• LABELS specifies that user header labels are to be punched. Labels cannot be 
edited. They are moved to the first 80 bytes of the output buffer. In this example, 
there are no sequence numbers present in the cards with user header and user 
trailer labels. 

In this example, the directory of a partitioned data set is to be printed. The input data 
set resides on a 2314 volume. The printed output is to be converted to hexadecimal. 

The example follows: 

//PRINTDIR JOB 09#660, SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=PDS,UNIT=2314,VOLUME=SER=111112, 

// DISP=( OLD , KEEP ) , DCB=( RECFM=U , BLKSIZE=256 ) 

//SYSUT2 DD SYSOUT=A 

DD * 

TYPORG=PS , TOTCONV=XE 

ITEM=( 'PRINT PARTITIONED DIRECTORY OF PDS ' , 1 ) 

ITEM=( 'FIRST TWO BYTES SHOW NUM OF USED BYTES ', 1 ) 

DATA=NO 



//SYSIN 

PRINT 

TITLE 

TITLE 
LABELS 
/* 

The control statements are discussed below: 



SYSUTl DD defines the input data set (the partitioned directory). 

SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains groups (8 characters each) of hexadecimal 
information. Six lines of print are required for each record. Each record begins a 
new line of printed output. 

SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT, TITLE, and LABELS statements. 

PRINT initiates the print operation, indicates that the partitioned directory is 
organized sequentially, and specifies conversion from alphameric to hexadecimal 
representation. 

The first TITLE statement specifies a title, which is not converted to hexadecimal. 
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lEBPTPCH Example 8 



lEBPTPCH Example 9 



• The second TITLE statement specifies a subtitle, which is not converted to 
hexadecimal. 

• LABELS specifies that no user labels are to be printed. 

Note: Not all of the bytes in a directory block need contain data pertaining to the 
partitioned data set; unused bytes are sometimes used by the operating system as 
temporary work areas. The first four characters of printed output indicate how many 
bytes of the 256-byte block pertain to the partitioned data set. Any unused bytes 
occur in the latter portion of the directory block; they are not interspersed with the 
used bytes. 

In this example, a card deck containing valid punch card code or BCD is to be 
duplicated. The input card deck resides in the input stream. 

The example follows: 



//PUNCH 

// 

//SYSPRINT DD 
//SYSIN DD 
//SYSUT2 DD 
//SYSUT1 DD 



JOB 09#660, SMITH 
EXEC PGM=IEBPTPCH 

SYSOUT=A 

DSNAME=PDSLIB( PNCHSTMT ) , DISP=( OLD , KEEP ) 

UNIT=2540-2 

DATA 



(input card data set including // cards) 

/* 

The control statements are discussed below: 

• SYSIN DD defines the control data set. The control data set contains a PUNCH 
statement and is defined as a member of the partitioned data set PDSLIB. (The 
data set is cataloged. The RECFM must be FB and the LRECL must be 80.) 

• SYSUT2 DD defines the output data set. The data set is to be punched on an IBM 
2540-2 Card Read Punch (punch feed). 

• SYSUTl DD defines the input card data set, which follows in the input stream. 

In this example a record group is to be printed. A user routine is provided to 
manipulate output records before they are printed. 

The example follows: 



//PRINT JOB 
// EXEC 

//SYSPRINT DD 
//SYSUTl DD 



09#660, SMITH 

PGM=IEBPTPCH 

SYSOUT=A 

DSNAME=SEQDS , UNIT=23 1 1 , DISP=( OLD, KEEP ) , 
// LABEL= ( , SUL ) , VOLUME=SER= 111112, 
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000 ) 



//SYSUT2 DD 

//SYSIN DD 

PRINT 

TITLE 

EXITS 

RECORD 

LABELS 



SYSOUT= 
* 



=A 



MAXFLDS=2 , MAXGPS= 1 , MAXLITS=6 , STOPAFT=32767 
ITEM=( ' TIMECONV-DEPT D06 ' ) , ITEM=( 'JAN 10-17' ) 
OUTREC=NEWTIME , INHDR=HDRS , INTLR=TLRS 
IDENT=( 6, '498414' , 1 ), «C 

FIELD=( 8 , 1 , , 1 ) , FIELD=( 30 , 9 , XE , 20 ) 
DATA=ALL , CONV=XE 



/* 

The control statements are discussed below: 

• SYSUTl DD defines the input data set. The data set resides on a 2311 volume. 

• SYSUT2 DD defines the output data set on the system output device (printer 
assumed). 

• SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT, TITLE, EXITS, and RECORD statements. 

• The PRINT statement: (1) initializes the print operation, (2) indicates that two 
FIELD parameters are included in subsequent RECORD statements, (3) indicates 
that one IDENT parameter is included in a subsequent RECORD statement, (4) 
indicates that six literal characters are included in the subsequent IDENT 
parameter, and (5) indicates that processing is to be terminated after 32,767 
records are processed or after the first record group is processed, whichever 
comes first. Because MAXLINE is omitted, 60 lines are printed on each page. 

o TITLE specifies a title. 

• EXITS specifies the name of a user routine (NEWTIME), which is used to manipulate 
output records before they are printed. 
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RECORD defines the record group to be processed and indicates where information 
from the input records is placed in the output records. Bytes 1 through 8 of the 
input records appear in columns 10 through 17 of the punched output, and bytes 9 
through 38 are printed in hexadecimal representation and placed in columns 20 
through 79. 

LABELS specifies that all user header or trailer labels are to be printed regardless 
of any return code, except 16, issued by the user's exit routine. It also indicates 
that the labels are to be converted from alphameric to hexadecimal representation. 



144 Utilities (Release 21.7) 



lEBTCRIN Program 



Error Records 



Error Description 
Word (EDW) 



Level Status (Byte 0) 



lEBTCRIN is a data set utility used to read input from the IBM 2495 Tape Cartridge 
Reader (TCR), edit tiie data as specified by tlie user, and produce a sequentially 
organized output data set. (See "Introduction" for general data set utility 
information.) 

The input to lEBTCRIN is in the form of cartridges written by either the IBM Magnetic 
Tape SELECTRIC Typewriter (MTST) or the IBM 50 Magnetic Data Inscriber (MTDI). 
An input data set (one or more cartridges) must consist of either all MTST cartridges 
or all MTDI cartridges. 

lEBTCRIN can be used to construct records from the stream of data bytes read 
sequentially from the Tape Cartridge Reader. The user has the option of gaining 
temporary control (via a user-supplied exit routine) to process each logical record. 

When MTDI input is edited, lEBTCRIN maintains information about each record as it is 
being edited. This information is summarized in the Error Description Word (EDW) 
which is described below. When the EDW contains a nonzero value in either the level 
status (byte 0) or the type status (byte 1), the record is considered an error record by 
the program and the EDW is appended to the start of the record to aid the user in 
analyzing the error. 

If a record is found to be in error, the record is passed to the user error exit routine if 
one is specified. If an error exit is not specified, the action to be taken is determined 
by the option specified in a utility control statement. 

When either MTST input or MTDI input without editing is specified, the only error that 
can be recognized is a record containing one or more permanent data checks. The 
data check bytes are replaced as described in a utility control statement. The record is 
considered an error record, but because a data check is the only error that can occur, 
no EDW is appended to the error record. 

The Error Description Word (EDW) consists of four bytes that are appended to the 
start of an error record. 

The error description word is in EBCDIC format; for example, a 2 is represented as 
X'F2' and a C is represented as X'C3'. The information provided in each of the four 
bytes of the EDW is discussed below. 

The level status indicator identifies error records that result from inter-record 
dependency that cannot be identified in the type status byte. 

The level status is presented with each error record and has a value of: 

• 0, for any error record that will not cause questionable data in following records. A 
nonzero type status accompanies this byte. 

• 1, for any error record that may cause questionable data in following records, and 
for which the level status of the previous record was 0. 

• 2, for any error record that contains questionable data because the error level of 
the preceding record was 1 or 2, or for any error record that may cause 
questionable data in the following records and for which the level status of the 
previous record was 1 or 2. 

A level status of other than is presented with error records resulting from the 
following: 

• The start-of-record (SCR) location has a character defined as an error. 

• The record contains two or more data check bytes side by side. These may have 
been an SCR and EGR. 

• The record is longer than the user-specified maximum length record. 

• The length of the record is not equal to the length of the first valid record of the 
same program level encountered on this cartridge. For this purpose, a valid record 
is one that contains no errors as identified in the type status, with the possible 
exception of being shorter than the user-specified minimum length. 

• The record has a data-duplication dependency on a previous record with one of the 
above errors. 

The level status is set to when lEBTCRIN encounters: (1) a record without one of the 
previous errors, (2) a canceled record, or (3) the first record of a cartridge. 
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Type Status (Byte 1) 



Start-of- Record (Byte 2) 



End-oi -Record (Byte 3) 



Sample Error Records 



The type status indicator identifies records in error because of SOR, EOR, length, 
field, or data check error conditions. 

The type status is presented with each error record and has a value of: 

• 0, for any record that contains none of the following identifiable errors, but 
contains questionable data due to a nonzero level status. (See "Level Status" 
earlier in this chapter.) 

• 1, for any record that has: (1) an SOR character of other than PI through P8 or a 
GS code, (2) an EOR character of other than a VOK code for records when the user 
specified a record verification check, or (3) an EOR character of other than a VOK 
or RM code for records when the user specified no record verification check. 

• 2, for any record that has an incorrect length because it is: (1) longer than the 
user-specified maximum, (2) shorter than the user-specified minimum, or (3) not 
equal to the length of the first valid record of the same program level encountered 
on this cartridge. 

• 4, for any record that has a field error. A field error occurs when duplication or 
left-zero justification functions did not occur in a field due to an error condition. 
See "MTDI Editing Criteria" below. 

• 8, for any record that has a permanent data check error. 

The type status indicator can also have values of 3, 5, 6, 7, 9, A, B, C, D, E, and F. 
These values indicate a combination of SOR, EOR, length, field, and data check errors. 
For example, a value of A indicates a record with a data check error (8) as well as an 
incorrect length (2). 

This byte contains an indication of the start-of-record (SOR) character associated 
with this record. The SOR character can be 1 through 8, where 1 indicates PI, 2 
indicates P2, etc., or E, which indicates that the SOR character is in error. 

This byte contains an indication of the end-of-record (EOR) character associated with 
this record. The EOR character can be: U, which indicates an unverified record; V, 
which indicates a verified record; or E, which indicates that the EOR character is in 
error. 

Figure 34 shows a stream of data bytes read sequentially from the tape cartridge 
reader. 

Figure 35 shows the records constructed by lEBTCRIN from the input records shown in 
Figure 34. These records show some of the errors that can occur during processing 
and their effect on the Error Description Word. The following parameters were 
specified on the TCRGEN statement for these records: 



TCRGEN TYPE = MTDI.EDIT = EDITR.VERCHK = VOKCHK, 
MAXLN = 50,REPLACE = X'5B' 



lie 



lEBTCRIN classifies records 2 through 9 in Figure 35 as error records. The records are 
classified, as follows: 

• Record 1 is a valid record. It contains a program level 1 code, and thus establishes 
the valid length for all program level 1 records in this cartridge to be 25 bytes. 

• Record 2 has a data check in the SOR location. Level status is set to 1 because the 
SOR location might have contained a cancel code that would cause any data 
duplicated on the following record to be questionable. The type status (9) indicates 
the record has an incorrect SOR/EOR character (1) and a data check error (8). 

• Record 3 contains no identifiable error, but contains questionable data because it 
requires duplication from the previous record, which had a level status of 1. 

• Record 4 has a data check. Because it contained no DUP codes, the level status is 
set to 0. 

• Record 5 is shorter than the first program level 1 record on this cartridge (length 
error). This record also contains an RM code rather than a VOK code in the EOR 
location (VOKCHK was specified). Because lEBTCRIN cannot determine why the 
record is short, all data duplicated from this record is questionable; the level status 
is set to 1. The type status is set to 3 indicating an SOR/EOR error (1) and length 
error (2). 

• Record 6 contains a DUP code that is beyond the last position of the preceding 
record. 
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MTDI Editing Criteria 



MTDI Editing Restrictions 



• The seventh input record is longer than the maximum user-specified record length. 
Note that it is passed as two records. The first record (record 7) indicates an EOR 
error and a length error; the second (record 8) indicates an SOR error. Because 
record 7 is an error record, its length (50 bytes) is not established as the valid 
length for all program level 3 records on this cartridge. 

• Record 9 has a data check. Because it contained no DUP codes, the level status is 
set to 0. 

The cartridges created on the IBM 50 Magnetic Data Inscriber contain a continuous 
stream of data bytes (that is, there are no interblock gaps). Therefore, when editing is 
specified, lEBTCRIN extracts records one at a time from the data stream. To 
accomplish this, lEBTCRIN scans for control codes written by MTDI. lEBTCRIN uses 
start-of-record (SOR) and end-of-record (EOR) locations to extract MTDI records 
from the input stream. 

The (SOR) location is defined as: 

• The location of the first character on a cartridge. 

• The location of the first character after the previous record's (EOR) location. 

• The location of an SOR code. 

• The location of a GS code. 

The character in the SOR location is checked to determine if it is a valid 
start-of-record character. A PI through P8, a cancel code, or a GS code are valid 
start-of-record characters; all others are invalid. 

The EOR location by priority sequence is: 

1. The same location as the SOR location, if the SOR character was a valid GS code. 

2. The location of the first encountered RM or VOK code if that location is within the 
length of the maximum user-specified record size. 

3. The location of any code preceding either a valid SOR code or the end-of-media 
code, if that location is within the length of the maximum user-specified record 
size. 

4. The location determined in 2 or 3, regardless of the maximum user-specified 
record size if the SOR location contains a cancel code. 

5. If one of the previous EOR locations cannot be defined, an EOR condition will be 
forced at the location where the record length equals the maximum user-specified 
record size. 

The character in the EOR location is checked to determine if it is a valid 
end-of-record character. Valid EOR characters are the GS character (if the SOR 
character was a GS code) and VOK or RM codes; all others are invalid. Each GS code 
is considered a valid SOR code or EOR code and will be bypassed. 

Following are the restrictions that apply when editing MDTI records: 

• All canceled records are bypassed; they are not passed to any exit routines or 
written on any data sets. The level status is set to 0. 

• All input records less than three bytes in length (SOR location, one data byte, and 
EOR location) are treated as canceled records. The remaining portion of a record 
that was longer than the user-specified maximum record size can result in an input 
record of this size. 

• Data duplication is accomplished by replacing the DUP code with the character 
from the corresponding location of the previous record. 

• The record used for data duplication is the record returned from any user exits. 

• GS codes will not affect the level status or duplication of following records. 

• Data duplication does not occur for any of the following conditions: 

1. The DUP code is encountered in the first record of a cartridge. 

2. The DUP code is encountered in a record immediately following a canceled 
record. A canceled record is one that contains a cancel code in the SOR location 
or an input record of less than three bytes as described above. 

3. The DUP code is encountered in a position that would cause duplication of a 
position beyond the last data byte of the previous record. 

4. The DUP code is encountered in a position that would cause duplication of an 
error-replace character. 
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End-of-Cartridge 



Input and Output 



Control 



Job Control Statements 



In each case, the DUP code is replaced with the user specified error-replace 
character, and a field error is indicated. 

o Left-zero justification does not occur; the left-zero fill code (LZ) is replaced with 
the user-specified error-replace character and a field error is indicated for either of 
the following conditions: 

1. The left-zero fill code (LZ) is encountered without first having encountered its 
corresponding left-zero start code (LZS). 

2. The user-specified maximum record size is exceeded before encountering the 
valid end of a left-zero field. 

Unique codes, written by the MTST or the MTDI device, signal the program when all 
data on a cartridge has been read. For MTST cartridges, this end- of -cartridge code is 
a lowercase stop code (st) or an uppercase stop code (ST). For MTDI cartridges, the 
end-of-cartridge code is the end-data code (ED). 

lEBTCRIN terminates input from a cartridge upon encountering the end-of-cartridge 
code and rewinds the cartridge. lEBTCRIN continues to process cartridges until 
end-of-file is encountered. 

End-of-file is signaled following a rewind operation when there are no more cartridges 
in the feed hopper, the END OF FILE button is pressed, and end-of-cartridge for the 
last cartridge is recognized. An end-of-file indication will be passed to the OUTREC 
and/or ERROR exits if specified by setting register 1 equal to 0. 

lEBTCRIN uses the following input: 

• An input data set, which contains data on tape cartridges to be read from the Tape 
Cartridge Reader (TCR). The input data set was created on either MTST or MTDI. 

• A control data set, which contains utility control statements that are used to control 
the functions of lEBTCRIN. 

lEBTCRIN produces the following output: 

• An output data set, which contains the sequential output produced by the utility as 
a result of processing the cartridge input according to the utility control statements. 

• An error output data set, which contains records that do not conform to the 
specifications for a valid record. 

• A message data set, which contains diagnostic messages. 

lEBTCRIN is controlled by job control statements and utility control statements. The 
job control statements are required to execute or invoke lEBTCRIN and to define the 
data sets that are used and produced by the program. The utility control statements 
are used to indicate the source of the input data cartridges (MTST or MTDI) and to 
specify the type of processing to be done. 

Table 25 shows the job control statements necessary for using lEBTCRIN. 

Table 25. lEBTCRIN Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = lEBTCRIN) or, if the job control statements 

reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set, which can be written to any 
QSAM-supported output device. 

SYSUTl DD Defines the input data set. 

SYSUT2 DD Defines a sequential output data set for valid records. 

SYSUT3 DD Defines a sequential output data set for error records. 

SYSIN DD Defines the control data set. The control data set normally resides in the input 

stream; however, it can be defined as a sequential data set or as a member of a 
partitioned data set. If this statement is not included, all utility control statement 
defaults are assumed and a message is issued to SYSPRINT. If DUMMY is 
specified, all utility control statement defaults are assumed. 

The minimum region size that can be specified for the execution of lEBTCRIN is 
12K + 2b + c + e, where (1) b is value specified for BUFL on the SYSUTl DD 
statement, (2) c is the maximum logical record length, and (3) e is the sum of user 
exit routines, each rounded to the next higher 2K. 

If the SYSPRINT DD statement is missing, a message is written on the operator 
console and processing continues. 
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Restrictions 



Utility Control Statements 



If some parameters are specified but others are omitted, lEBCTRIN attempts to set 
defaults for the missing parameters that are consistent with those supplied. For 
example, if RECFM = VBA is specified, lEBTCRIN assumes BLKSIZE = 129 and 
LRECL = 125. If LRECL, BLKSIZE, and RECFM are not specified, the defaults are 
LRECL = 121, BLKSIZE = 121, and RECFM = FBA. 

For the SYSUTl DD statement, only the UNIT keyword is required. The value specified 
in UNIT = xxxx can be '2495', the device address, or any other name that was 
generated in the system as a unit device name. The VOLUME = SER = keyword may 
be specified to identify the tape cartridges to be mounted. The volume serial number 
must be an externally recognizable name associated with the cartridges to be 
processed. A message is issued to the operator instructing that the cartridges 
identified by that name be mounted. If VOLUME is not specified, the name TCRINP is 
assumed and used in the mount message. The BUFL DCB parameter can be specified 
to indicate the size of input buffers; if BUFL is not specified, a value of 2000 is 
assumed. 

Fixed and variable records on the SYSUT2 or SYSUT3 data set can be blocked through 
the specification of the BLKSIZE and RECFM DCB parameters. 

SYSUT2 DD and SYSUT3 DD statements may be omitted or specified as DUMMY. A 
message is issued on SYSPRINT and processing continues. 

The DCB parameters defining the SYSIN, SYSPRINT, SYSUT2, and SYSUT3 data sets 
can be supplied from any valid source (for example, DD statements or a data set 
label). Because the output (SYSUT2 and/or SYSUT3) data sets are not opened until 
the first record is ready for output (after any OUTREC and/or ERROR exits), DCB 
parameters to be supplied from an existing data set label are not available for records 
constructed before the data set is opened. Therefore, the DCB parameters should 
always be provided in the DD statement even though they may already exist in the 
label. Otherwise, defaults are used to construct records until the data set is opened. 

If a permanent error occurs on SYSIN, SYSUTl (not including a data check), SYSUT2, 
or SYSUT3, a message is issued on SYSPRINT and the program is terminated. If a 
permanent input/output error occurs on SYSPRINT, both the failing message and a 
SYNADAF message indicating the error, are written on the programmer's console and 
processing is terminated. 

• Because lEBTCRIN always constructs the SYSPRINT records with USASI (type A) 
control characters, type A control characters should be indicated when RECFM is 
specified. 

• If a parameter is specified on SYSPRINT DD that is not consistent with the other 
parameters, a message is issued and processing is ended. 

• The SYSUTl DD statement is required for each use of lEBTCRIN. 

• The SYSUT2 DD and SYSUT3 DD statements must identify sequential data sets; the 
data sets can have fixed, variable, variable spanned, or undefined records. These 
data sets can be written on any QSAM-supported device. 

• If editing of MTDI input is specified on the utility control statements, the SYSUT3 
LRECL parameter should be four bytes greater than the SYSUT2 LRECL parameter 
to include a four-byte Error Descriptor Word appended to the front of the record by 
lEBTCRIN. (See "Error Records" earlier in this chapter.) For variable records on 
either SYSUT2 or SYSUT3, the LRECL and BLKSIZE DCB parameters must be large 
enough to include the four-byte record descriptor word. 

• If inconsistent parameters are specified on SYSUT2 DD or SYSUT3 DD, a message 
is issued and processing is ended. 

lEBTCRIN is controlled by the following utility control statements: 

• TCRGEN statement, which specifies whether MTDI or MTST input is to be 
processed and the type of processing to be performed. 

• EXITS statement, which specifies any exit routines provided by the user. 

If these statements contain errors or inconsistencies, the program is terminated and 
the appropriate diagnostics are sent to the message data set. If TCRGEN is not 
specified, standard defaults are used. 

Note: If TCRGEN or EXITS is specified, the operand must be made up of one or more 
parameters. 
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TCRGEN Statement The TCRGEN statement is used to indicate the device (MTDI or IVITST) on which the 

input data was created and the type of processing to be performed on the input data. 

The format of the TCRGEN statement is: 



[label'] TCRGEN [TYPE = ( MTDI } 

{MTST}] 
[JRANS= ( STDUC } 
{STDLC } 
{name } 
{NOTRAN}] 
[,EDIT= l EDlTD } 
{EDITR } 
{NOEDIT}] 
[,VERCHK= {NOCHK } 
{VOKCHK }] 
[,MINLN = n ] 
[,MAXLN = n] 
.REPLACE = X'xx' 

[,ERROPT= ( NORMAL ) 
{NOERR }] 
wliere: 

TYPE = 

specifies the device on which the magnetic tape cartridge(s) was written. These 
values can be coded: 

MTDI 

specifies that the input was created on a Magnetic Data Inscriber. This is the 
default. 

MTST 

specifies that the input was created on a Magnetic Tape SELECTRIC typewriter. 

TRANS = 

specifies the type of processing to be performed on MTST input. These values can 
be coded: 

STDUC 

specifies that the MTST code is to be translated to standard EBCDIC; alphabetic 
characters are translated to uppercase. This is the default. 

STDLC 

specifies that the MTST code is to be translated to standard EBCDIC; alphabetic 
characters are not translated to uppercase. 

name 

specifies a user-translate table to be used by lEBTCRIN. The translate table 
must exist as a load module named in a user job library or the link library. This 
load module must consist of a translate table which begins at the entry point and 
conforms to the specifications for the translate instruction (TR) found in IBM 
System/ 360 Principles of Operation, GA22-6821. 

NOTRAN 

specifies that no translation and no special processing is to be performed. Data 
is passed exactly as read from the cartridge. 

EDIT = 

specifies the type of processing to be performed on MTDI input. These values can 
be coded: 

EDITD 

specifies that the input is to be edited and that SOR and EOR codes are to be 
deleted and not included as part of the output record. This is the default. 

EDITR 

specifies that the input is to be edited and SOR and EOR codes are to be kept as 
part of the output record. 

NOEDIT 

specifies that no editing is to be performed. Data, including any group separator 
(GS) codes, is passed exactly as read from the cartridge. 
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VERCHK = 

specifies whether a record-verification checl< is to be made on MIDI input that is to 
be edited. This parameter is valid only when TYPE = MTDI and either EDIT = EDITD 
or EDIT = EDITR are specified. These values can be coded: 

NOCHK 

specifies that no record-verification check is to be made. Either a record mark 
(RM) or a verify OK (VOK) code is considered a valid end-of-record code. This 
is the default. 

VOKCHK 

specifies that a record-verification check is to be made. A record that does not 
contain a verify OK code is to be considered an error record. 

MINLN = n 

specifies in bytes the length, n, of the shortest valid edited record. This parameter 
is valid only when TYPE = MTDI and either EDIT = EDITD or EDIT = EDITR are 
specified. If lEBTCRIN encounters a record shorter than this specified length, the 
record is considered an error record. If MINLN is omitted, no minimum length 
checking is performed. 

MAXLN = n 

specifies the number of bytes, n, plus four for the record descriptor word when 
variable records are specified, to be contained in all but the last record passed to 
the output routine when editing is not performed. lEBTCRIN does not indicate the 
end of data from one cartridge and the beginning of data from the next. Usually this 
transition from one cartridge to another occurs within an output record. The last 
record passed to the output routine contains only the number of bytes remaining 
(plus four if the record format is variable) and is the only record that can be shorter 
than the length specified by MAXLN. The size of the records actually written 
depends on the record length (LRECL) specified for the output data set. If MAXLN 
is omitted, a value of 120 is assumed. 

REPLACE = X'xx' 

specifies the hexadecimal representation of the character to be used by lEBTCRIN 
to replace error bytes. REPLACE allows the user to identify and possibly correct 
error bytes in the error exit routine or in subsequent processing. The specified 
REPLACE character should be one that does not normally appear in the data. X'19', 
end-of-data, is assumed if REPLACE is not coded. To replace error bytes on MTDI 
data, select a value for xx from Figure 36. to replace error bytes on MTST data, 
select a value for xx from Figure 37. The replacement of error bytes is 
accomplished before any specified MTST translation. 

ERROPT = 

specifies the disposition of all error records. ERROPT is ignored if a user error 
routine is specified in the EXITS statement. These values can be coded: 

NORMAL 

specifies that all error records are to be placed in the error data set (SYSUT3). 

NOERR 

specifies that all records (including error records) are placed in the normal 
output data set (SYSUT2). No records are placed in the error data set 
(SYSUT3). This is the default. 

If STDUC, STDLC, or name is specified, certain of the MTST codes are processed in a 
special way before translation. Feed codes (FD), switch codes (SW), and autosearch 
codes (AS), both uppercase and lowercase, are deleted from the data. Each 
61 -character reference code is reduced to a single search code (SRC). 

A stop code, whether uppercase (ST) or lowercase (st), indicates that all data on a 
cartridge has been read. Therefore, when an MTST cartridge to be processed by 
lEBTCRIN is created, the user must not use a stop code for any purpose other than 
signaling end-of-data on the cartridge. Stop codes within meaningful data cause any 
subsequent data on the cartridge to be lost because the cartridge is rewound and 
unloaded when a stop code is encountered. 

If EDITD or EDITR is specified, the edit consists of the following functions: 

• Records are extracted one at a time from the input buffers by scanning for the 
record-delimiting codes (SOR and EOR). 

• DUP codes are replaced with the character from the corresponding location in the 
preceding record. 

• Left-zero fields are right aligned and leading zeros are inserted where necessary. 
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• Left-zero start codes are deleted from the records. 

• Group separator codes and records that start with cancel record codes are 
bypassed. 

For MIDI input with editing specified, MAXLN is used to specify in bytes the length of 
the longest valid record after editing. If the program encounters a record in which a 
valid end-of-record cannot be determined within this length, an end-of-record 
condition is forced and the record is considered an error record. 

The values that can be specified for MINLN and MAXLN are: 

• For MTST processing or MIDI processing without editing, MINLN is not specified. 
MAXLN should equal the number of bytes to be passed as a record. 

• For MIDI processing when EDIT = EDITD, MINLN should equal the number of bytes 
in the shortest valid record after editing, excluding SOR and EOR codes. MAXLN 
should equal the number of bytes in the longest valid record after editing, excluding 
SOR and EOR codes. 

• For MIDI processing when EDIT = EDITR, MINLN should equal the number of bytes 
in the shortest valid record after editing, including SOR and EOR codes. MAXLN 
should equal the number of bytes in the longest valid record after editing, including 
SOR and EOR codes. 

Note: The values for MINLN and MAXLN should not include the four-byte record 
descriptor word added to a variable length record. 

Table 26 shows the hexadecimal characters representing special purpose codes that 
must not be used as replacement bytes. 

Table 26. Special Purpose Codes 
MTDI Codes 



X'OO' (LZ) 


X'lE' 


(VOK) 


X'74' 


(P4) 


x'lr (DUP) 


X'3C' 


(RM) 


X'75' 


(P5) 


X'12' (LZS) 


X'71' 


(PI) 


X'76' 


(P6) 


X'18' (CAN) 


X'72' 


(P2) 


X'77' 


(P7) 


X'lD' (GS) 


X'73' 


(P3) 


X'78' 


(P8) 


MTST Codes 










X'lO' (cr) 


X'14' 


(OR) 


X'51' 


(as) 


X'll' (sw) 


X'15' 


(SW) 


X'55' 


(AS) 


X'13' (fd) 


X'17' 


(FD) 


X'BO' 
X'81 \ 


(src) 
through X'FF' 



The special purpose codes listed in Table 26 are used by lEBTCRIN when constructing 
records. Use of these codes causes a message to be issued and the utility to be 
terminated. 

Figure 36 shows the values that can be chosen to replace error bytes for MTDI input. 

Figure 37 shows the values that can be chosen to replace error bytes for MTST input. 

Figure 38 shows MTST codes after they have been translated by lEBTCRIN when 
TRANS = STDLC is specified. 

EXITS Statement The EXITS statement is used to identify user-supplied exit routines, which must exist 

in either the user job library or the link library. 

Upon entry, a parameter list is supplied to the exit routine Upon returning from the 
exit routine, the user must provide an acceptable return code. See "Appendix A: Exit 
Routine Linkage." 

The format of the EXITS statement is: 

[labef] EXITS [ERROR = routinename] \ 

[.OUTREC = routinename] j 

[,0UTHDR2 = routinename] I 

[.OUTHDRS = routinename] \ 

[,0UTTLR2 = routinename] \ 

[.GUTTLRS = routinename] \ 
where: 

ERROR = routinename 

specifies the symbolic name of a routine that receives control before an error 
record is passed to the error output data set (SYSUT3). This exit routine can be 
used to analyze and, if possible, correct the error record. This parameter nullifies 
any ERROPT value. 
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This figure represents the character set and control 
codes as read from an MTDI created cartridge. 



Bit Positions 0,1 
Bit Positions 2, 3 
First Hexadecimal Digit 



Special Control: 

LZ = Left zero fill 

DUP = Duplicate 

LZS = Left zero start 

ED = End data 

GS = Group Separator 



Start of Record (SOR): 



PI = 
P2 = 
P3 = 
P4 = 
P5 = 
P6 = 
P7 = 
P8 = 
CAN 



Program level 1 
Program level 2 
Program level 3 
Program level 4 
Program level 5 
Program level 6 
Program level 7 
Program level 8 
= Cancel 



End of Record (EOR): 

RM = Record mark 
VOK = Verify OK 



Figure 36. MTDI Codes from TCR 



OUTREC = routinename 

specifies the symbolic name of a routine that receives control before the record is 
passed to the normal output data set (SYSUT2). In this exit routine, the user can 
process the record and perform his own output if output other than the SYSUT2 
data set is desired. Any modification of an edited MTDI record may affect the 
editing of following records because the record returned from this exit is used to 
accomplish data duplication in the record that follows. If the SYSUT2 data set has 
specified variable length records, a four-byte RDW is appended to the front of the 
record. 



0UTHDR2 = routinename 

specifies the symbolic name of a routine that receives control during the opening of 
the SYSUT2 data set; this exit routine can be used to create user output header 
labels for the normal output data set (SYSUT2). 

0UTHDR3 = routinename 

specifies the symbolic name of a routine that receives control during the opening of 
the SYSUT3 data set; this exit routine can be used to create user output header 
labels for the error data set (SYSUT3). 

0UTTLR2 = routinename 

specifies the symbolic name of a routine that receives control during the closing of 
the SYSUT2 data set; this exit routine can be used to create user output trailer 
labels for the normal output data set (SYSUT2). 
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0UTTLR3 = routinename 

specifies the symbolic name of a routine that receives control during the closing of 
the SYSUT3 data set; this exit routine can be used to create user output trailer 
labels for the error data set (SYSUT3). 

If MIDI is edited, a four-byte (EDW) is appended to the front of each error record 
describing the error condition. For further definition of the EDW, see "Error Records" 
earlier in this chapter. If the SYSUT3 DD statement specified variable length records, 
a four-byte Record Descriptor Word (RDW) is also appended to the front of the 
record. For further description of the RDW, see OS Supervisor Services Guide, 
GC28-6646. 
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This figure represents the character set and control 
codes as read from an MTST created cartridge. 



Bit Positions 0, 1 
Bit Positions 2, 3 
First Hexadecinrial Digit 



cr and CR 
sw and SW 
fdand FD 
st and ST 
tab and TAB 
as and AS 
sp and SP 
bsp and BSP 
stx and STX 
src and SRC 



Carrier return code 
Switch code 
Feed code 
Stop code 
■ Tab code 

• Automatic search 
' Space 

' Bacl<space 

• Stop transfer 

• Search 



Figure 37. MTST Codes from TCP 



The user-supplied routines specified in ERROR and OUTREC can be used to examine 
and modify any byte in the record or EDW. The record length can be changed, subject 
to the following restrictions: 

• A work area used to construct the records is allocated by the program equal in size 
to the largest of (1) MAXLN, (2) LRECL on SYSUT2, or (3) LRECL on SYSUT3. 

• The record length must not be increased beyond this size. Overlaying of other work 
areas may then occur, causing unpredictable results. 

The new record length must be placed in the location pointed to by the second 
parameter word as received at entry to the routine. This length must include the EDW 
and RDW (if applicable). It is not necessary to modify the RDW because it is 
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re-created if the record is to be written by lEBTCRIN. However, if tiie user does his 
own output from this routine, he must ensure that the RDW is correct for the record. 
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Note: The STDUC option permits translating 
both lowercase and uppercase alphabetic 
characters to uppercase. 



Bit Positions 0,1 
Bit Positions 2, 3 
First Hexadecimal Digit 



TAB = Tab code 

CR = Carrier return 

BSP = Backspace 

SRC = Search 

STX = Stop transfer 

SP = Space 



Figure 38. MTST Codes after Translation by lEBTCRIN with TRANS = STDCL 



If lEBTCRIN is to write the record, the length of the output record depends on the 
REX^FM specification, as follows: 

• Fixed and variable records may have a maximum length equal to LRECL Records 
larger than this are truncated. 

• Undefined records may have a maximum length equal to BLKSIZE. Records larger 
than this are truncated. 

These record lengths include the EDW and RDW, where applicable. 

The record length returned from the error exit is used to establish the location of the 
last data byte in the record. The location is used to control data duplication in the 
following record. However, it is not used for checking the record length of subsequent 
records. 

Modifications to the EDW, record, or record length may affect the editing of 
subsequent records. If the input is not edited, the user can examine and modify any 
byte in the record. The record length can also be changed, subject to the MTDI editing 
restrictions. 
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Return Codes from 
lEBTCRIN 



lEBTCRIN Examples 



At job termination, lEBTCRIN produces a return code to indicate the results of 
program execution. Table 27 shows the return codes used by lEBTCRIN. 

Table 27. lEBTCRIN Return Codes 

Return 

Code Interpretation 

00 Normal termination. 

04 Warning message issued; execution permitted. Conditions leading to issuance of this 

code are: (1) SYSPRINT, SYSIN, SYSUT2, or SYSUT3 DD statements missing and (2) 
DOB parameters missing in SYSUT2 or SYSUT3 DD statements. 

12 Diagnostic error message issued; execution terminated. Conditions leading to issuance 

of this code are: (1) SYSUTl DD statement missing, (2) conflicting DCB parameters in 
DD statements, and (3) invalid or conflicting utility control statements. 

16 Terminal error message issued; execution terminated. Conditions leading to issuance 

of this code are: (1) permanent input/output errors (not including data checks on the 
TOR), (2) unsuccessful opening of data sets, (3) requests for termination by user exit 
routine, (4) insufficient storage available for execution, and (5) user exit routine not 
found. 

The following examples illustrate some of the uses of lEBTCRIN. Table 28 can be used 
as a quick reference guide to lEBTCRIN examples. The numbers in the "Example" 
column point to examples that follow. 



Table 28. lEBTCRIN Example Directory 



lEBTCRIN Example 1 



Operation 
Edit MDTI input 

Invoke lEBTCRIN 
with LINK macro 
instruction 



Data Set 
Organization 

Sequential 



Device 

2314 Disk, 
9-track tape 



Comments Example 

Fixed blocked output. Error 

exit routine specified 1 



In this example, input from a tape cartridge is to be edited with normal records written 
to a 2314 volume and error records written to a 9-track tape volume. 



The example follows: 



//JOBNAME JOB 
//STPNAME EXEC 
//SYSPRINT DD 
//SYSUTl DD 
//SYSUT2 DD 



, SMITH , MSGLEVEL= 1 

PGM=IEBTCRIN 

SYSOUT=A 

UNIT=TCR, VOLUME=SER=MYTAPE,DCB=( BUFL=3000 ) 

DSNAME=GOODSET, DISP=( NEW, CATLG ) , UNIT=23 1 4 , 
// V0LUME=SER=1 1 1 222 ,SPACE=( TRK, ( 10,10)), 
// DCB=(LRECL=100,BLKSIZE=1000,REDFM=FB) 
//SYSUT3 DD DSNAME=ERRSET,UNIT=2400, 
// VOLUME=SER=0 00001 ,DISP=( NEW, KEEP ) , 
// DCB={BLKSIZE=104,RECFM=U) 
//SYSIN DD * 

TCRGEN TYPE=MTDI , EDIT=EDITD , MAXLN= 100, REPLACE=X ' 5B ' 
EXITS ERROR=MYERR 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the input tape cartridge data set. A console message instructs 
the operator to mount a set of cartridges named MYTAPE. The two input buffers 
are each 3000 bytes long (BUFL). The UNIT parameter assumes that TCR has been 
system generated as a unit name for the Tape Cartridge Reader. 

• SYSUT2 DD defines a sequential data set for the normal output records. The data 
will be written to a 2314 volume. 

• SYSUT3 DD defines a sequential data set for the error records. The records are 
undefined with a maximum block size of 104 bytes, including a 4-byte error 
description word. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• TCRGEN indicates MTDI input. The input is to be edited with SOR and EOR codes 
deleted, the maximum valid record length is to be 100 bytes, and the replace 
character is a hexadecimal "5B". VERCHK is defaulted to NOCHK. Minimum record 
length checking is not requested. 
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• EXITS indicates that a user has provided an exit routine to handle error records. 
Because no job library has been specified, the exit routine (MYERR) must reside in 
the link library. 

lEBTCRIN Example 2 In this example, lEBTCRIN is invoked via the LINK macro instruction in an Assembler 

language program. An alternate name has been assigned to each of the DD 
statements used by lEBTCRIN. The job control for this step must include DD 
statements with the alternate DD names. 

The example follows: 

LINK EP=IEBTCRIN,PARAiyi=(0PTLIST,DDNAME),VL=1 

CNOP 2,4 (OPTLIST must be on halfword boundary) 

OPTLIST DC H'O' (Length must be zero for lEBTCRIN) 

CNOP 2,4 (DDNAME list must be on halfword boundary) 

DDNAME DC H'82' (Length of DDNAME list) 

DC 8F'0' 

DC C'NEWIN • (Alternate DDNAME for SYSIN) 

DC C'NEWPRINT' (Alternate DDNAME for SYSPRINT) 

DC 2F'0' 

DC C'NEWUTI • (Alternate DDNAMEforSYSUTl) 

DC C'NEWUT2 ' (Alternate DDNAME for SYSUT2) 

DC C'NEWUT3 ' (Alternate DDNAME for SYSUT3) 
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lEBUPDAT Program-Class C 



Input and Output 



Control 

Job Control Statements 



FARM Information on 
the EXEC Statement 



lEBUPDAT is a data set utility used to incorporate IBM- and user-generated source 
language modifications into a symbolic library — a partitioned data set containing 
80-byte records, sucli as SYSl.PROCLIB and SYSl.MACLIB. (See "Introduction" for 
general data set utility information.) 

lEBUPDAT can be used to: 

• Add, copy, and replace members. 

• Add, delete, replace, and renumber the records within an existing member. 

• Assign sequence numbers to the records of a new member. 
lEBUPDAT uses the following input: 

• A partitioned input data set, which contains an old master data set. 

• A sequential input data set, which contains the transactions that are to be applied 
to the old master data set. 

• A control data set, which contains utility control statements. 

lEBUPDAT produces as output a new master partitioned data set and a sequential 
data set (SYSPRINT) that reflects either the latest changes applied to the old master 
data set or to the entire new master data set. 

lEBUPDAT is controlled by job control statements and utility control statements. 

Table 29 shows the job control statements necessary for using lEBUPDAT. 

Table 29. lEBUPDAT Job Control Statements 

Statement Use 

Initiates an lEBUPDAT job. 

Specifies the program name (PGM = lEBUPDAT). Additional information can be 
specified on the EXEC statement; see "PARM Information on the EXEC 
Statement" below. 

Defines an input data set. 

Defines an output data set. 

Defines the sequential message data set. 

Defines the control data set. 



JOB 
EXEC 

SYSUTl DD 
SYSUT2 DD 
SYSPRINT DD 
SYSiN DD 



The minimum region size that can be specified for lEBUPDAT is lOK + 2b, where b is 
the largest block size in the job step rounded to the next higher 2K. 

The input data set defined by SYSUTl and the output data set defined by SYSUT2 can 
contain either blocked or unblocked records with a logical record length of 80 bytes. 
The output data set can have a blocking factor different from the input data set. 

If the DD statements SYSUTl and SYSUT2 define the same data set, the user can 
make modifications to the old master without creating a new master. 

If enough space cannot be allocated for reblocked output records, the update request 
is terminated. 

lEBUPDAT obtains control information through the EXEC statement and the SYSIN 
data set. The EXEC statement for this program may contain the parameter: 

PARM = (input,[inhdr],[intlr]) 

The input value is either NEW or MOD, as follows: 

• NEW, which indicates that the input consists of the SYSIN data set. 

• MOD, which indicates that the input consists of both the SYSIN and SYSUTl data 
sets. 

The SYSUTl data set need not be defined if NEW is specified. If the input value is 
neither NEW nor MOD, an error is indicated and the operation is terminated. If an 
input value is not specified, MOD is assumed. 

The "inhdr" value specifies the symbolic name of a routine that processes the user 
header label on the SYSIN data set. 
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utility Control Statements 



Header Statement 



The "intir" value specifies the symbolic name of a routine that processes the user 
trailer label on the SYSIN data set. 

The utility control statements used to control lEBUPDAT are shown in the order in 
which they must appear, as follows: 

• Header statement, which is used to identify members to be processed. 

• NUMBR statement, which is used to identify the sequence number of records to be 
processed. 

• DELET statement, which is used to identify records to be deleted. 

• Logical Record, which contains data to be added to or to replace an existing 
record. 

• ALIAS statement, which is used to create or retain aliases in a new master 
directory. 

• ENDUP statement, which indicates the end of the SYSIN input to lEBUPDAT. 

The SYSIN data set can contain any number of Header statements and ALIAS 
statements, each followed by a group of NUMBR, DELET, Logical Record, and ALIAS 
statements. 

A Header statement is used to identify a member to be processed. The statements 
must be in binary collating sequence by member name. 

The format of the Header statement is: 



•/ 



where: 

•/ 



{ADD } membername,levet,source,risti,ss}] 
{REPL } 
{CHNGE } 
{REPRO } 



is required and must appear in columns 1 and 2. 

ADD 

specifies that the named member is to be added in its entirety to the new master. If 
ADD is included, it must begin in column 10. 

REPL 

specifies that the named member is being entered in its entirety as a replacement 
for a member in the old master. If REPL is included, it must begin in column 10. 

CHNGE 

specifies that modifications are to be made within the named member. If CHNGE is 
included, it must begin in column 10. 

REPRO 

specifies that the entire named member is to be copied to the new master. 
Members are deleted from a library by being omitted from a series of REPRO 
Header statements. If REPRO is included, it must begin in column 10. 

membername 

specifies the name of the member to which the update transactions are to be 
applied. The membername value must begin in column 16. 

level 

specifies the current run number, a two-digit number from 00 through 99. 

source 

specifies whether user or IBM modifications are to be made. The values that can be 
coded are: 



list 



specifies user modifications. 

specifies IBM modifications. 

specifies what the SYSPRINT data set is to contain. The values that can be coded 
are: 



specifies that the SYSPRINT data set is to contain only modifications and control 
statements. 
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NUMBR Statement 



specifies that the SYSPRINT data set is to contain the entire updated member 
and control statements. 

55/ 

specifies eight hexadecimal characters of new system status index information that 
is to be placed In the directory of the new master as the first four hexadecimal 
bytes of user data. If ss/ is not specified, the user data is copied as it exists in the 
directory of the old master. System status index information is discussed in detail in 
IBM System/ 360 Operating System: Maintenance, GC27-6918. 

The NUMBR statement contains information to be applied to the member that is 
named in the Header statement. 

The NUMBR statement is used with CHNGE Header statements to change the 
sequence number of one or more logical records within a member, and with ADD and 
REPL Header statements to assign sequence numbers to the records within new and 
replacing members. This statement affects only those sequence numbers that fall in 
the specified range. 

The format of the NUMBR statement is: 

NUMBR seqnumbl,seqnumb2,newseq,increment 



where: 

•/ 

is required and must appear in columns 1 and 2. 

NUMBR 

specifies that this is a NUMBR statement. NUMBR must begin in column 10. 

seqnumbl 

specifies the sequence number of the first record to be renumbered when used with 
a CHNGE Header statement. This value is ignored when used with ADD and REPL 
Header statements. This value must be contained in columns 16 through 23. 



DELET Statement 



is a delimiter, which must appear in columns 24, 33, and 42. 

seqnumb2 

specifies the sequence number of the last record to be renumbered when used with 
a CHNGE Header statement. This value is ignored when used with ADD and REPL 
Header statements. 

newseq 

specifies the first new sequence number. This value must be contained in columns 
34 through 41. 

increment 

specifies the increment value of successive new sequence numbers. This value 
must be contained in columns 43 through 50. 

All of the sequence numbers must be eight-digit alphameric fields. 

The DELET statement contains information to be applied to the member that is named 
in the Header statement. 

The DELET statement is used to delete one or more logical records within a member. 
It is used only in conjunction with a CHNGE Header statement. 

The format of the DELET statement is: 

./ DELET seqnumb J, seqnumb2 

where: 

■/ 

is required and must appear in columns 1 and 2. 

DELET 

specifies that this is a DELET statement. DELET must begin in column 10. 

seqnumbl 

specifies the sequence number of the first logical record to be deleted. This value 
must begin in column 16 and not extend beyond column 23. 

is a delimiter, which must appear in column 24. 



lEBUPDAT Program - Class C 161 



Logical Record Statement 



ALIAS Statement 



ENDUP Statement 



lEBUPDAT Examples 



seqnumb2 

specifies the sequence number of the last logical record to be deleted. This value 
must begin in column 25 and cannot extend beyond column 32. 

The Logical Record statement contains information to be applied to the member that 
is named in the Header statement. The Logical Record statements contain the data to 
be added to, or used to replace, existing logical records. They are used in conjunction 
with ADD, REPL, or CHNGE Header statements. 

The format of the Logical Record statement is: 

data 

where: 

data 



record -sequence- number 



is the data to be added to or to replace a record. This value must be contained in 
columns 1 through 72. 

record-sequence-number 

specifies the sequence number of the record to be processed. This value must be 
contained in columns 73 through 80. 

The ALIAS statement is used to create or retain aliases in a new master directory. The 
ALIAS statement can be used in conjunction with any of the Header statements. One 
ALIAS statement must be supplied for each alias. 

The format of the ALIAS statement is: 

./ ALIAS aliasname 

where: 

■/ 

is required and must appear in columns 1 and 2. 

ALIAS 

specifies that this is an ALIAS statement. ALIAS must begin in column 10. 

aliasname 

specifies an alias. The a//asname value must begin in column 16. 

If system status index information is provided for the member name, it is also inserted 
into the alias entry in the directory of the new master. 

The ENDUP statement can be used to indicate the end of the SYSIN input to this 
program; it serves as an end-of-data indication if there is no other indication. The 
ENDUP statement follows the last group of SYSIN control statements. 

The format of the ENDUP statement is: 

; ./ ENDUP 

where: 

./ 

is required and must appear in columns 1 and 2. 

ENDUP 

specifies that this is an ENDUP statement. ENDUP must begin in column 10. 

The examples that follow illustrate some of the uses of lEBUPDAT. Table 30 can be 
used as a quick reference guide to lEBUPDAT examples. The numbers in the 
"Example" column point to examples that follow. 



Table 30. lEBUPDAT Example Directory 

Operation Comments Example 

CATALOG Job control statements are cataloged In 1 
the procedure library. 

REPLACE A member of a symbolic library is replaced. 2 

DELETE Records are deleted from a symbolic library. 3 

COPY A member of a symbolic library is copied. 4 

CREATE A three-member library is created. 5 
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lEBUPDAT Example 1 



lEBUPDAT Example 2 



lEBUPDAT Example 3 



lEBUPDAT Example 4 



In this example, a set of job control statements are cataloged in the cataloged 
procedure library. 

The example follows: 

//UPD1 JOB 09#770, D.P.BROWN 

// EXEC PGM=IEBUPDAT,PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//S YSUT2 DD (Definition of cataloged procedure library) 

//SYSIN DD DATA 

./ ADD PROC6,05,0,1 

./ NUMBR 00000000,00000000,00000010,00000010 

//STEP1 EXEC 

//DD1 DD 

//STEP EXEC 

/* 

PR0C6 will be added to the cataloged procedure library defined in SYSUT2. The first 
record of this procedure will contain the sequence number 00000010 with successive 
records numbered 00000020, 00000030, etc. The resulting cataloged procedure can 
be executed with an EXEC statement specifying PROC = PR0C6. For additional 
information on cataloged procedures, see OS JCL Reference, GC28-6704. 

In this example, a member in the old master is replaced by a new member. 

The example follows: 



//UPD2 JOB 

// EXEC 

//SYSPRINT DD 

//SYSUT1 DD 

//SYSUT2 DD 

//SYSIN DD 
./ 
./ 



09#770, D.P.BROWN 

PGM=IEBUPDAT , PARM=MOD 

SYSOUT=A 

(Definition of old master data set) 

(Definition of new master data set) 

* 

REPL MBR7,06,0,1 

NUMBR 00000000,00000000,00000010,00000010 



(Logical Record statements) 

./ ALIAS ALS7 

/* 

MBR7 (alias ALS7) replaces MBR7 of the library named in SYSUTl. Successive 
records in the new member will contain the sequence numbers 00000010, 00000020, 
etc. 

In this example, logical records are deleted from a member of a symbolic library. 

The example follows: 



//UPD3 JOB 
// EXEC 

//SYSPRINT DD 



09#770, D.P.BROWN 

PGM= lEBUPDAT 

SYSOUT=A 

(Definition of old master data set) 

(Definition of new master data set) 

* 

CHNGE MBRS ,13,0,1 
DELET 00000050,00000090 
ALIAS ALS5 



DD 
DD 
DD 



//SYSUTl 

//SYSUT2 

//SYSIN 

./ 

./ 

./ 

/* 

Logical records 00000050 through 00000090 are deleted from a symbolic library. 
In this example, a member from an old master tape is copied to a new master. 
The example follows: 



//UPD4 JOB 
// EXEC 

//SYSPRINT DD 
//SYSUTl DD 



09#770, D.P.BROWN 

PGM= lEBUPDAT , PARM=MOD 

SYSOUT=A 

(Definition of old master data set) 
//SYSUT2 DD (Definition of new master data set) 
//SYSIN DD * 

. / REPRO MBRZ ,12,0,1 

/* 

Member MBRZ, run number 12, is copied from the old master. The SYSPRINT data set 
is to contain the entire updated member and control statements. 
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lEBUPDAT Example 5 



In this example, a three-member libary is created; the members are named 
LIBMEMBl, LIBMEMB2, and LIBMEMB3. 

The example follows: 

//UPD5 JOB 09# 7 70, D.P.BROWN 

// EXEC PGM=IEBUPDAT,PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD (Definition of new master data set) 

//SYSIN DD * 

./ ADD LIBMEMBl ,01 ,0, 1 , 1234ABCD 

(Logical Record statements) 

./ ADD LIBMEMB2,01 ,0, 1 , 1234EFAB 

(Logical Record statements) 

./ ADD LIBMEMB3,01 ,0, 1 , 1234ABAB 

(Logical Record statements) 

/* 

The control statements are discussed below: 

• SYSUT2 DD defines a master data set to which the new members are to be written. 

• The first ADD Header statement specifies that LIBMEMBl is to be added to the new 
master data set. 

• The first set of Logical Record statements contain the records that are to become 
LIBMEMBl. 

• The second ADD Header statement specifies that LIBMEMB2 is to be added to the 
new master data set. 

• The second set of Logical Record statements contain the records that are to 
become LIBMEMB2. 

• The third ADD Header statement specifies that LIBMEMB2 is to be added to the 
new master data set. 

• The third set of Logical Record statements contain the records that are to become 
LIBMEMB3. 
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lEBUPDTE Program 



Creating and Updating 
Symbolic Libraries 



Incorporating Changes 



Changing Data Set 
Organization 



Input and Output 



lEBUPDTE is a data set utility used to incorporate IBM and user-generated source 
language modifications into sequential or partitioned data sets. (See "Introduction" 
for general data set utility information.) Exits are provided for user routines that 
process user header and trailer labels. 

lEBUPDTE can be used to: 

• Create and update symbolic libraries. 

• Incorporate changes to partitioned members or sequential data sets. 

• Change the organization of a data set from sequential to partitioned or vice versa. 

At the completion or termination of lEBUPDTE, the highest return code encountered 
within the program is passed to the calling program. 

lEBUPDTE can be used to create a library of partitioned members consisting of 
(at the most) 80-byte logical records. In addition, members can be added directly to 
an existing library, provided that the original space allocations are sufficient to 
incorporate the new members. In this manner, a cataloged procedure can be placed 
in a procedure library, or a set of job or utility control statements can be placed as a 
member in a partitioned library. 

lEBUPDTE can be used to modify an existing partitioned or sequential data set. Logical 
records can be replaced, deleted, renumbered, or added to the member or data set. 

A sequential data set residing on a tape volume can be used to create a new master 
(that is, a modified copy) of the data set. A sequential data set residing on a direct 
access device can be modified either by creating a new master or by modifying the 
data set directly on the volume on which it resides. 

A partitioned data set can be modified either by creating a new master or by 
modifying the data set directly on the volume on which it resides. 

lEBUPDTE can be used to change the organization of a data set from sequential to 
partitioned, or to change a member of a partitioned data set to a sequential data set 
(the original data set, however, remains unchanged). In addition, logical records can 
be replaced, deleted, renumbered, or added to the member or data set. 

lEBUPDTE uses the following input: 

• An input data set (also called the old master data set), which is to be modified or 
used as source data for a new master. The input data set is either a sequential data 
set or a member of a partitioned data set. 

• A control data set, which contains utility control statements and, if applicable, input 
data. The data set is required for each use of lEBUPDTE. 

lEBUPDTE produces the following output: 

• An output data set, which is the result of the lEBUPDTE operation. The data set can 
be either sequential or partitioned. It can be either a new data set (that is, created 
during the present job step) or an existing data set, modified during the present job 
step. 

• A message data set, which contains the utility program identification, control 
statements used in the job step, modification made to the input data set, and 
diagnostic messages, if applicable. The message data set is sequential. 

lEBUPDTE provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• GO, which indicates successful completion. 

• 04, which indicates that a control statement is coded incorrectly or used 
erroneously. If either the input or output is sequential, the job step is terminated. If 
both are partitioned, the program continues processing with the next function to be 
performed. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

• 16, which indicates that a label processing code of 16 was received from a user's 
label processing routine. The job step is terminated. 
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Control 



Job Control Statements 



lEBUPDTE is controlled by job control statements and utility control statements. The 
job control statements are required to execute or invoke lEBUPDTE and to define the 
data sets that are used and produced by the program. The utility control statements 
are used to control the functions of lEBUPDTE and, in certain cases, to supply new or 
replacement data. 

Table 31 shows the job control statements necessary for using lEBUPDTE. 



Restrictions 



Table 31. lEBUPDTE Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGIVI = lEBUPDTE), or, if the job control statements 

reside in a procedure library, the procedure name. Additional information can be 
specified in the PARIVI parameter of the EXEC statement; see "PARM Information 
on the EXEC Statement" below. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a system 
output device, a tape volume, or a direct access volume. 

SYSUTl DD Defines the input (old master) data set. It can define a sequential data set on a 
card reader, a tape volume, or a direct access volume. Or, it can define a 
partitioned data set on a direct access volume. This DD statement is not required 
if the input consists solely of the control data set. 

SYSUT2 DD Defines the output data set. It can define a sequential data set on a card punch, a 
printer, a tape volume, or a direct access device. It can define a partitioned data 
set on a direct access device. 

SYSIN DD Defines the control data set. The control data set normally resides in the input 

stream; however, it can be defined as a member of a partitioned data set. 

The minimum region size that can be specified for lEBUPDTE Is 14K + 2b, where b is 
the largest block size in the job step rounded to the next higher 2K. 

The input and output data sets contain blocked or unblocked logical records with 
record lengths of up to 80 bytes. The input and output data sets may have different 
block sizes as long as they are multiples of the logical record length. 

I If an ADD operation is specified with PARM = NEW on the EXEC card, the SYSUTl DD 
statement need not be coded. See "PARM Information on the EXEC Statement" 
below. Refer to "Function Statement" below for a discussion of the ADD operation. 

If an UPDATE operation is specified, the SYSUT2 DD statement should not be coded. 
Refer to "Function Statement" for a discussion of the UPDATE operation. 

If the SYSUTl DD statement defines a sequential data set, the file sequence number 
of that data set must be included in the LABEL keyword (unless the data set is the first 
or only data set on the volume). 

If both the SYSUTl and SYSUT2 DD statements specify standard user labels (SUL), 
lEBUPDTE copies user labels from SYSUTl to SYSUT2. See "Appendix E: Processing 
User Labels" for a discussion of the available options for user label processing. 

If the SYSUTl and SYSUT2 DD statements define the same partitioned data set, the 
old master data set can be updated without creating a new master data set; in this 
case, a copy of the updated member or members is written within the extent of the 
space originally allocated to the old master data set. Subsequent referrals to the 
updated member(s) will point to the newly written member(s). The member names 
themselves should not appear on the DD statements; they should be referenced only 
through lEBUPDTE control statements. 

• The SYSPRINT DD statement is required for each use of lEBUPDTE. 

• The output data set can have a blocking factor that is different from the input data 
set; however, if insufficient space is allocated for reblocked records, the update 
request is terminated. 

• When adding a member to an existing partitioned data set using an ADD Function 
statement, any DCB parameters specified on the SYSUTl and SYSUT2 DD 
statements (or the SYSUT2 DD statement if that is the only one specified) must be 
the same as the DCB parameters already existing for the data set. 

• Space must be allocated for an output data set (SYSUT2 DD statement) that is to 
reside on a direct access device, unless the data set is an existing data set, in 
which case space should not be allocated. 

• The SYSUT2 DD statement must not specify a DUMMY data set. 
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FARM Information on 
the EXEC Statement 



Utility Control Statements 



Function Statement 



• If the SYSUTl and SYSUT2 DD statements define the same sequential data set 
(direct access only), only those operations that add data to the end of the existing 
data set can be made. In these cases: 

1. The PARM parameter of the EXEC statement must imply or specify MOD. (See 
"PARM Information on the EXEC Statement" below.) 

2. The DISP parameter of the SYSUTl DD statement must specify OLD. 

3. The DISP parameter of the SYSUT2 DD statement must specify MOD. 

• The SYSIN DD statement is required for each use of lEBUPDTE. 

• The message data set has a logical record length of 121 bytes, and consists of 
fixed length, blocked or unblocked records with an ASA control character in the 
first byte of each record. The input and output data sets have a logical record 
length of 80 bytes or less, and consist of fixed blocked (RECFM = FB) or unblocked 
records. The control data set contains 80-byte, blocked or unblocked records. 

Additional information can be coded in the PARM parameter of the EXEC statement, 
as follows: 

PARM = ( {NEW },[inhdr],[intlr]) 
( MOD } 

Following are the PARM values: 

• NEW, which specifies that the input consists solely of the control data set. The 
input data set is not defined if NEW is specified. 

• MOD, which specifies that the input consists of both the control data set and the 
input data set. If neither NEW nor MOD is coded, MOD is assumed. 

• "inhdr," which specifies the symbolic name of a routine that processes the user 
header label on the volume containing the control data set. 

• "intir," which specifies the symbolic name of a routine that processes the user 
trailer label on the volume containing the control data set. 

For a detailed discussion of the processing of user labels as data set descriptors, refer 
to "Appendix E: Processing User Labels." 

The utility control statements used to control lEBUPDTE are: 

• Function statement, which is used to initiate an lEBUPDTE operation. 

• Detail statement, which is used with the Function statement for special applications. 

• Data statement, which is a logical record of data to be used as a new or 
replacement record in the output data set 

• LABEL statement, which is used to indicate that the following data statements are 
to be treated as user labels. 

• ALIAS statement, which is used to assign aliases. 

• ENDUP statement, which is used to terminate lEBUPDTE. 

The Function statement is used to initiate an lEBUPDTE operation. At least one 
Function statement must be provided for each member or data set to be processed. 

A member or a data set can be added directly to an old master data set if the space 
originally allocated to the old master is sufficient to incorporate that new member or 
data set. 

When a member replaces an identically named member on the old master data set or 
a member is changed and rewritten on the old master, the alias (if any) of the original 
member still refers to the original member. However, if an identical alias is specified 
for the newly written member, the original alias entry in the directory is changed to 
refer to the newly written member. 
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The format of the Function statement is: 



./[name] {ADD } [LIST = ALL] 
{REPL } 
I {CHANGE } [,SEQFLD = ddl] 

{REPRO } 

[,NEW={PO}] 
{PS} 
[.MEMBER = cccccccc] 
[,COLUMN = dd] 
[.UPDATE = INPLACE] 
[.INHDR = cccccccc] 
[.INTLR = cccccccc] 
[.OUTHDR = cccccccc] 
[.OUTTLR = cccccccc] 
[.TOTAL = (routinename,stze)] 
[.NAME = cccccccc] 
[.LEVEL = hh] 
[.SOURCE = X] 
ISS\ = hhhhhhhh] 
where: 

■/ 

is required and must appear in columns 1 and 2. 

name 

specifies an optional name which begins in column 3 and extends no further than 
column 10. 

ADD 

(specifies that a member or a data set is to be added to an old master data set. If a 
member is to be added and the member name already exists in the old master data 
set, processing is terminated. If, however, PARM = NEW is specified on the EXEC 
statement, the member is replaced. For a sequential output master data set, 
PARM = NEW must always be specified on the EXEC statement. At least one blank 
must precede and follow ADD. 

REPL 

specifies that a member of a data set is being entered in its entirety as a 
replacement for a sequential data set or for a member of the old master data set. 
The member name must already exist in the old master data set. At least one blank 
must precede and follow REPL. 

CHANGE 

specifies that modifications are to be made to an existing member or data set. Use 
of the CHANGE Function statement without a NUMBER or DELETE Detail statement, 
or a Data statement causes an error condition. At least one blank must precede 
and follow CHANGE. 

REPRO 

specifies that a member or a data set is to be copied in its entirety to a new master 
data set. At least one blank must precede and follow REPRO. 

LIST = ALL 

specifies that the SYSPRINT data set is to contain the entire updated member or 
data set and the control statements used in its creation. If LIST is omitted, the 
SYSPRINT data set contains modifications and control statements only. If UPDATE 
was specified, the entire updated member is listed only when renumbering has 
been done. 

I SEQFLD = dd/ 

specifies, in decimal, the starting column (up to column 80) and length (8 or less) 
of sequence numbers within existing logical records and subsequent Data 

(statements. Note that the starting column specification (dd) plus the length (I) 
cannot exceed LRECL +1. If SEQFLD is omitted, 738 is assumed, that is, an 
eight-byte sequence number beginning in column 73. Therefore, if existing logical 
records and subsequent Data statements have sequence numbers in columns 73 
through 80, this keyword need not be coded. In any case, sequence numbers on 
incoming Data statements and existing logical records must be padded to the left 
with enough zeros to fill the length of the sequence field. 
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NEW = 

specifies the organization of the old master data set and the organization of the 
updated output. NEW should not be specified unless the organization of the new 
master data set is different from the organization of the old master. Refer to Table 
31 for the use of NEW with NAME and MEMBER. These values can be coded: 

PO 

specifies that the old master data set is a sequential data set, and that the 
updated output is to become a member of a partitioned data set. 

PS 

specifies that the old master data set is a partitioned data set, and that a 
member of that data set is to be converted into a sequential data set. 

MEMBER = cccccccc 

specifies a name to be assigned to the member placed in the partitioned data set 
defined by the SYSUT2 DD statement. MEMBER is used only when SYSUTl defines 
a sequential data set, SYSUT2 defines a partitioned data set, and NEW = PO is 
specified. Refer to Table 32 for the use of MEMBER with NEW. 

COLUMN = dd 

specifies, in decimal, the starting column of a data field within a logical record 
Image. The field extends to the end of the image. Within an existing logical record, 
the data in the defined field is replaced by data from a subsequent Data statement. 
COLUMN is valid only when CHANGE is coded. 

UPDATE = INPLACE 

specifies that the old master data set is to be updated within the space it actually 
occupies. The old master data set must reside on a direct-access device. UPDATE 
is valid only when coded with CHANGE. 

INHDR = cccccccc 

specifies the symbolic name of the user routine that handles any user input 
(SYSUTl) header labels. When used with UPDATE, this routine assumes a special 
function. This parameter is valid only when a sequential data set is being 
processed. See "LABEL Statement" for a discussion of this function. 

INTLR = cccccccc 

specifies the symbolic name of the user routine that handles any user input 
(SYSUTl) trailer labels. INTLR is valid only when a sequential data set is being 
processed, but not when UPDATE is coded. 

OUTHDR = cccccccc 

specifies the symbolic name of the user routine that handles any user output 
(SYSUT2) header labels. OUTHDR is valid only when a sequential data set is being 
processed, but not when UPDATE is coded. 

OUTTLR = cccccccc 

specifies the symbolic name of the user routine that handles any user output 
(SYSUT2) trailer labels. OUTTLR is valid only when a sequential data set is being 
processed, but not when UPDATE Is coded. 

TOTAL = 

specifies that exits to a user's routine are to be provided prior to writing each 
record. This parameter is valid only when a sequential data set is being processed. 
These values are coded: 

routinename 

specifies the name of the user's totaling routine. 

size 

specifies the number of bytes required for the user's data. The size should not 
exceed 32K, nor be less than 2 bytes. In addition, the keyword OPTCD = T must 
be specified for the SYSUT2 (output) DD statement. Refer to "Appendix A: Exit 
Routine Linkage" for a discussion of linkage conventions for user routines. 

NAME = cccccccc 

indicates the name of the member placed into the partitioned data set. The 
member name need not be specified in the DD statement itself. NAME must be 
provided to identify each input member. Refer to Table 32 for the use of NAME 
with NEW. This parameter is valid only when a member of a partitioned data set is 
being processed. 

LEVEL = hh 

specifies the change (update) level in hexadecimal (00-FF). The level number is 
recorded in the directory entry of the output member. This parameter is valid only 
when a member of a partitioned data set is being processed. 
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SOURCE = X 

specifies user modifications when the x value is 0, or IBM modifications when the x 
value is 1. The source is recorded in the directory entry of the output member. This 
parameter is valid only when a member of a partitioned data set is being 
processed. 

SSI = hhhhhhhh 

specifies eight hexadecimal characters of system status information (SSI) to be 
placed in the directory of the new master data set as four packed hexadecimal 
bytes of user data. This parameter is valid only when a member of a partitioned 
data set is being processed. SSI overrides any LEVEL or SOURCE data given on the 
same Function statement. 

Members can be deleted from a copy of a library by being omitted from a series of 
REPRO Function statements within the same job step. 

One sequential data set can be copied in a given job step. A sequential data set is 
deleted by being omitted from a series of job steps which copy only the desired data 
sets to a new volume. If the NEW subparameter is coded in the EXEC statement, only 
the ADD Function statement is permitted. 

Figure 39 shows how the system status information (SSI = 0A3C123B) is packed. 
Refer to IBM System/360 Operating System: Maintenance, GC27-6918, for a detailed 
discussion of the format of system status information. 



Change level 
byte 1 


Flag byte 
byte 2 


Serial number 
byte 3 


byte 4 


A 


3 C 


1 2 


3 B 



Figure 39. Format of System Status Information 



When UPDATE is specified: 

• The SYSUT2 DD statement need not be coded. 

• The PARM parameter of the EXEC statement must imply or specify MOD. 

• The NUMBER statement can be used to specify a renumbering operation, 
e Data statements can be used to specify replacement information only. 

• One CHANGE Function statement and one UPDATE parameter are permitted per job 
step. 

• No functions other than replacement, renumbering, and header label modification 
(via the LABEL statement) can be specified. 

• Only replaced records are listed unless the entire data set is renumbered. 

• System status information cannot be changed. 

Within an existing logical record, the data in the field defined by COLUMN is replaced 
by data from a subsequent data statement, as follows: 

1. lEBUPDTE matches a sequence number of a Data statement with a sequence 
number of an existing logical record. In this manner, the COLUMN specification is 
applied to a specific logical record. 

2. The information in the field within the Data statement replaces the information in 
the field within the existing logical record. For example, COLUMN = 40 indicates 
that columns 40 through 80 (assuming 80-byte logical records) of a subsequent 
Data statement are to be used as replacement data for columns 40 through 80 of a 
logical record identified by a matching sequence number. (A sequence number in 
an existing logical record or Data statement need not be within the defined field.) 

The COLUMN specification applies to the entire function, with the exception of: 

• Logical records deleted by a subsequent DELETE Detail statement. 

• Subsequent Data statements not having a matching sequence number for an 
existing logical record. 

• Data statements containing information to be inserted in the place of a deleted 
logical record or records. 
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Table 32 shows the use of NEW, MEMBER, and NAME parameters for different input 
and output data set organizations. 

Table 32. NEW. MEMBER, and NAME Parameters 

Input Data Set Output Data Set Parameter 
Organization Organization Combinations 

Partitioned Partitioned With an ADD Function statement, use NAIVIE to specify the 

name of the member to be placed in the partitioned data 
set defined by the SYSUT2 DD statement. If an additional 
name is required, an ALIAS statement can also be used. 

With a CHANGE, REPL, or REPRO Function statement, use 
NAME to specify the name of the member within the 
partitioned data set defined by the SYSUTl DD statement. 
If a different or additional name is desired for the member 
in the partitioned data set defined by the SYSUT2 DD 
statement, use an ALIAS statement also. 

None Partitioned (New) With each ADD Function statement, use NAME to assign a 

name for each member to be placed in the partitioned 
data set. 

Partitioned Sequential With a Function statement, use NAME to specify the name 

of the member in the partitioned data set defined by the 
SYSUTl DD statement. Use NEW = PS to specify the 
change in organization from partitioned to sequential. (The 
name and file sequence number assigned to the output 
master data set are specified in the SYSUT2 DD 
statement.) 

Sequential Partitioned With a Function statement, use MEMBER to assign a name 

to the member to be placed in the partitioned data set 
defined by the SYSUT2 DD statement. Use NEW = PO to 
specify the change in organization from sequential to 
partitioned. 

For a detailed discussion of the processing of user labels as data set descriptors, and 
for a discussion of user-label totaling, see "Appendix E: Processing User Labels." 

Detail Statement A Detail statement is used with a Function statement for certain applications, such as 

deleting or renumbering selected logical records. 

Note: Logical records cannot be deleted in part; that is, a COLUMN specification in a 
Function statement is not applicable to records that are to be deleted. Each specific 
sequence number is handled only once in any single operation. 

The format of a Detail statement is: 

? ./[name} {NUMBER }[SEQ1 « {cccccccc }] 
i {DELETE } {ALL } 

I [,SEQ2 « cccccccc] 

[,NEW1 = cccccccc] 

[,INCR = cccccccc] 

wh'ere"™'"""""'''"'"'""''""""'™'"*^''*'"'''''""""'"'™"'" ""-— -^---— -— - "- 

■/ 

is required and must appear in columns 1 and 2. 

name 

specifies an optional name which begins in column 3 and extends no further than 
column 10. 

NUMBER 

specifies, when coded with a CHANGE Function statement, that the sequence 
number of one or more logical records is to be changed. It specifies, when coded 
with an ADD or REPL Function statement, the sequence numbers to be assigned to 
the records within new or replacement members or data sets. When used with an 
ADD or REPL Function statement, no more than one NUMBER Detail statement is 
permitted for each ADD or REPL Function statement. If NUMBER is coded, it must 
be preceded and followed by at least one blank. 

DELETE 

specifies, when coded with a CHANGE Function statement, that one or more logical 
records is to be deleted from a member or data set. If DELETE is coded, it must be 
preceded and followed by at least one blank. 
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SEQl = 

specifies records to be renumbered, deleted, or assigned sequence numbers. 
These values can be coded: 

cccccccc 

specifies the sequence number of the first logical record to be renumbered or 
deleted. This value is not coded in a NUMBER Detail statement that is used with 
an ADD or REPL Function statement. When this value is used in an insert 
operation, it specifies the existing logical record after which an insert is to be 
made. It must not equal the number of a statement just replaced or added. Refer 
to the INSERT parameter for additional discussion. 

ALL 

specifies a renumbering operation for the entire member or data set. ALL is used 
only when a CHANGE Function statement and a NUMBER Detail statement are 
used. ALL must be coded if sequence numbers are to be assigned to existing 
logical records having blank sequence numbers. If ALL is not coded, all existing 
logical records having blank sequence numbers are copied directly to the output 
master data set. When ALL is coded: (1) SEQ2 need not be coded and (2) one 
NUMBER Detail statement is permitted per Function statement. Refer to the 
INSERT parameter for additional discussion. 

SEQ2 = cccccccc 

specifies the sequence number of the last logical record to be renumbered or 
deleted. If only one record is to be deleted, the SEQl and SEQ2 specifications must 
be identical. SEQ2 is not coded in a NUMBER Detail statement that is used with an 
ADD or REPL Function statement. 

NEWl = cccccccc 

specifies the first sequence number assigned to new or replacement data, or 
specifies the first sequence number assigned in a renumbering operation. A value 
specified in NEWl must be greater than a value specified in SEQl (unless 
SEQl = ALL is specified, in which case this rule does not apply). This parameter is 
valid only in a NUMBER Detail statement. 

INCR = cccccccc 

specifies an increment value used for assigning successive sequence numbers to 
new or replacement logical records, or specifies an increment value used for 
renumbering existing logical records. This parameter is valid only in a NUMBER 
Detail statement. 

INSERT = YES 

specifies the insertion of a block of logical records. The records, which are Data 
statements containing blank sequence numbers, are numbered and inserted in the 
output master data set. INSERT is valid only when coded with both a CHANGE 
Function statement and a NUMBER Detail statement. 

When INSERT is coded: 

• The SEQl parameter specifies the existing logical record after which the insertion is 
to be made. The SEQ2 parameter need not be coded; SEQl = ALL cannot be 
coded. 

• The NEWl parameter assigns a sequence number to the first logical record to be 
inserted. 

• The INCR parameter is used to renumber as much as is necessary of the member 
or data set from the point of the first insertion; the member or data set is 
renumbered until an existing logical record is found whose sequence number is 
equal to or greater than the next sequence number to be assigned. If no such 
logical record is found, the entire member or data set is renumbered. 

• Additional NUMBER Detail statements, if any, must specify INSERT. If a prior 
numbering operation renumbers the logical record specified in the SEQl parameter 
of a subsequent NUMBER Detail statement, any NEWl or INCR parameter 
specifications in the latter NUMBER statement are overridden. The prior increment 
value is used to assign the next successive sequence numbers. If a prior numbering 
operation does not renumber the logical record specified in the SEQl parameter of 
a subsequent NUMBER Detail statement, the latter statement must contain NEWl 
and INCR specifications. 

• The block of Data statements to be inserted must contain blank sequence numbers. 

• The insert operation Is terminated when a Function statement, a Detail statement, 
an end-of-file indication, or a Data statement containing a sequence number is 
encountered. 



172 Utilities (Release 21.7) 



Data Statement 



LABEL Statement 



The SEQl, SEQ2, NEWl, and INCR parameters (with the exception of SEQ = ALL) 
specify eight-character (maximum) decimal numbers. Only the significant numbers of 
a value need be coded; for example, SEQl = 00000010 can be shortened to 
SEQl = 10. 

A Data statement is used with a Function statement, or with a Function statement and 
a Detail statement. It contains a logical record used as replacement data for an 
existing logical record, or new data to be incorporated in the output master data set. 

Each Data statement contains one logical record, which begins in the first column of 
the Data statement. The length of the logical record is equal to the logical record 
length (LRECL) specified for the output master data set. Each logical record contains a 
sequence number to determine where the data is to be placed in the output master 
data set. 

When used with a CHANGE Function statement, a Data statement contains new or 
replacement data, as follows: 

• If the sequence number in the Data statement is identical with a sequence number 
in an existing logical record, the Data statement replaces the existing logical record 
in the output master data set. 

• If no corresponding sequence number is found within the existing records, the Data 
statement is inserted in the proper collating sequence within the output master 
data set. (For proper execution of this function, all records in the old master data 
set must have a sequence number.) 

• If a Data statement with a sequence number is used and INSERT = YES was 
specified, the insert operation is terminated. lEBUPDTE will continue processing if 
this sequence number is at least equal to the next old master record (record 
following the referred to sequence record). 

When used with an ADD or REPL Function statement, a Data statement contains new 
data to be placed in the output master data set. 

Sequence numbers within the old master data set are assumed to be in ascending 
order. 

Sequence numbers in Data statements must be in the same relative position as 
sequence numbers in existing logical records. (Sequence numbers are assumed to be 
in columns 73 through 80; if the numbers are in columns other than these, the length 
and relative position must be specified in a SEQFLD parameter within a preceding 
Function statement.) 

The sequence number of the Data statement must always be equal to or greater than 
the sequence number of the next old master record. 

The LABEL statement indicates that the following Data statements are to be treated as 
user labels. These new user labels are placed on the output data set. The next 
Function statement indicates to lEBUPDTE that the last label data statement of the 
group has been read. 

There can be no more than two LABEL statements per execution of lEBUPDTE. There 
can be no more than eight label data statements following any LABEL statement. The 
first four bytes of each 80-byte label data statement must contain "UHLn" or 
"UTLn", where n is 1 through 8, for input header or input trailer labels respectively, to 
conform to IBM standards for user labels. Otherwise, data management will overlay 
the data with the proper four characters. 

When lEBUPDTE encounters a LABEL statement, it reads up to eight Data statements 
and saves them for processing by user output label routines. If there are no such 
routines, the saved records are written by OPEN or CLOSE as user labels on the 
output data set. If there are user output label processing routines, lEBUPDTE passes a 
parameter list to the output label routines. This parameter list is described fully in 
"Appendix A: Exit Routine Linkage." The label buffer contains a label data record 
which the user routine can process before the record is written as a label. If the user 
routine specifies (via return codes to lEBUPDTE) more entries than there are label 
data records, the label buffer will contain meaningless information for the remaining 
entries to the user routine. 

The position of the LABEL statement in the SYSIN data set, relative to Function 
statements, indicates the type of user label that follows the LABEL statement: 

• To create output header labels, place the LABEL statement and its associated label 
data statements before any Function statements in the input stream. A Function 
statement other than LABEL must follow the last label data statement of the group. 
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• To create output trailer labels, place the LABEL statement and its associated label 
data statements after any Function statements in the input stream, but before the 
ENDUP statement. The ENDUP statement is not optional in this case. It must follow 
the last label data statement of the group if lEBUPDTE is to create output trailer 
labels. lEBUPDTE will continue processing if this sequence number is at least equal 
to the next old master record (record following the referred to sequence record). 

When UPDATE is specified in a Function statement, user input header labels can be 
updated by user routines, but input trailer and output labels cannot be updated by 
user routines. User labels cannot be added or deleted. User input header labels are 
made available to user routines by the label buffer address in the parameter list. See 
"Appendix E: Processing User Labels" for a complete discussion of the linkage 
between utility programs and user label-processing routines. The return codes when 
UPDATE is used differ slightly from the standard codes discussed in "Appendix E: 
Processing User Labels," as follows: 

• 0, which specifies that the system resumes normal processing; any additional user 
labels are ignored. 

• 4, which specifies that the system does not write the label. The next user label is 
read into the label buffer area and control is returned to the user's routine. If there 
are no more user labels, the system resumes normal processing. 

• 8, which specifies that the system writes the user labels from the label buffer area 
and resumes normal processing. 

• 12, which specifies that the system writes the user label from the label buffer area, 
then reads the next input label into the label buffer area and returns control to the 
label processing routine. If there are no more user labels, the system resumes 
normal processing. 

If the user wants to examine the replaced labels from the old master data set, he 
must: 

1. Specify an update of the old master by coding the UPDATE parameter in a Function 
statement. 

2. Include a LABEL statement in the input data set for either header or trailer labels. 

3. Specify a corresponding user label routine. 

If the above conditions are met, fourth and fifth parameter words will be added to the 
standard parameter list. The fourth parameter word is not now used; the fifth contains 
a pointer to the replaced label from the old master. In this case, the number of labels 
supplied in the SYSIN data set must not exceed the number of labels on the old 
master data set. If the user specifies, via return codes, more entries to the user's 
header label routine than there are labels in the input stream, the first parameter will 
point to the current header label on the old master data set for the remaining entries. 
In this case, the fifth parameter is meaningless. 

Note: DATA = NO must be specified to make standard user label (SUL) exits inactive 
when input/output data sets with nonstandard labels (NSL) are to be processed. 

The ALIAS statement is used to create or retain an alias in an output (partitioned) 
master directory. The ALIAS statement can be used with any of the Function 
statements. Multiple aliases can be assigned to each member. 

The format of the ALIAS statement is: 



./[name] 
where: 



ALIAS NAME = cccccccc 



./ 



is required and must appear in columns 1 and 2. 



name 

specifies an optional name which begins in column 3 and extends no further than 
column 10. 

NAME = cccccccc 

specifies a one- to eight-character alias. 

ALIAS must be preceded and followed by at least one blank. If multiple ALIAS 
statements are used, they must follow the data records. 
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lEBUPDTE Examples 



An ENDUP statement can be used to indicate the end of SYSIN input to this job step. 
It serves as an end-of-data indication if there is no other indication. The ENDUP 
statement follows the last group of SYSIN control statements. 

The format of the ENDUP statement is: 



ENDUP 



./[name] 
where: 

•/ 

is required and must appear in columns 1 and 2. 

name 

specifies an optional name which begins in column 3 and extends no further than 
column 10. 

ENDUP must be preceded and followed by at least one blank. The ENDUP statement 
must follow the last label data statement if lEBUPDTE is used to create output trailer 
labels. 

The following examples illustrate some of the uses of lEBUPDTE. Table 33 can be used 
as a quick reference guide to lEBUPDTE examples. The numbers in the "Example" 
column point to examples that follow. 



Table 33. lEBUPDTE Example Directory 

Data set 
Operation Organization Device 



Comments Example 

2314 Disks SYSUTl and SYSUT2 DD statements 
define the same data set. Procedure 
to be cataloged is in the control 
data set. 1 

2314 Disk Input data is in the control data set. 

Output partitioned data set is to contain 

three members. 2 

2314 Disk Input from control data set and from 
existing partitioned data set. Output 
partitioned data set is to contain four 
members. 3 

2314 Disk Input data set is considered to be the 
output data set as well; therefore, no 
SYSUT2 DD statement is required. 4 

3330 Disk Sequential master is to be created from 

9-track tape partitioned tape input. Selected 

records are to be deleted. Blocked 

output. 5 

9-track tape, Partitioned data set is to be created 
2314 Disk from sequential input. Records are to 

be deleted and updated. Sequence 

numbers in columns other than 73 

through 80. One member is to be 

placed in the output data set. 6 

2314 Disks Block of logical records is to be 
inserted into an existing member. 
SYSUTl and SYSUT2 DD statements 
define the same data set. 7 

2314 Disks Two blocks of logical records are to be 
inserted into an existing member. 
SYSUTl and SYSUT2 DD statements 
define the same data set. 8 

Card Reader, Sequential data set with user labels is 

2314 Disk to be created from card input. 9 

2314 Disks Sequential data set is to be copied 
from one direct access volume to 
another; user labels can be processed 
by exit routines. 10 



CATALOG a 
procedure 



CREATE a 

partitioned 

library 

CREATE a 
partitioned 
data set 

UDPATE 
INPLACE and 
renumber 

CREATE and 
DELETE 



CREATE, 
DELETE, and 
UPDATE 



INSERT 



Partitioned 



Partitioned 



Partitioned 



Partitioned 



Partitioned, 
Sequential 



Sequential, 
Partitioned 



Partitioned 



INSERT Partitioned 

CREATE Sequential 

COPY Sequential 
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//UPDATE 


JOB 


// 


EXEC 


//SYSPRINT 


DD 


//SYSUT1 


DD 


//SYSUT2 


DD 


//SYSIN 


DD 


./ 


ADD 


. / NUMBER 


//ERASE 


EXEC 


//DD1 


DD 


//SYSPRINT 


DD 


. / ENDUP 


/* 





In this example, a procedure is to be placed in the cataloged procedure library, 
SYSl.PROCLIB. The example assumes that the new procedure (ERASE) can be 
accommodated within the space originally allocated to the procedure library; 
therefore, the update operation is performed directly to the old master. 

The example follows: 

09#660, SMITH 
EXEC PGM=IEBUPDTE , PARM=MOD 
SYSOUT=A 

DSNAME=SYS 1 . PROCLIB , DISP=( OLD , KEEP ) 
DSNAME=SYS1 . PROCLIB, DISP=( OLD, KEEP ) 
DATA 

LIST=ALL , NAME=ERASE , LEVEL=0 1 , SOURCE=0 
NEW1=10,INCR=10 
PGM=IEHPROGM 

UNIT=190,DISP=(OLD,KEEP),VOLUME=SER=11 1111 
SYSOUT=A 



The control statements are discussed below: 

• SYSUTl and SYSUT2 DD define the SYSl.PROCLIB data set, which is assumed to 
be cataloged. 

• SYSIN DD defines the control data set. The data set contains the utility control 
statements and the data to be placed in the procedure library. 

• The ADD Function statement indicates that records (Data statements) in the control 
data set are to be placed in the output. The newly created procedure is to be listed 
in the message data set. 

• The NUMBER Detail statement indicates that the new procedure is assigned 
sequence numbers. The first record of the procedure is assigned sequence number 
10; the remaining two records are assigned sequence numbers 20 and 30., 

The ERASE EXEC, DDl, and SYSPRINT DD statements are placed in the cataloged 
procedure library, SYSl.PROCLIB, as a result of this job. 

Note: The resulting procedure can be executed with an EXEC statement specifying 
PROC = ERASE. For additional information on cataloged procedures, see OS JCL 
Reference, GC28-6704. 

In this example, a three-member, partitioned library is to be created. The input data is 
contained solely in the control data set. 

The example follows: 



//UPDATE 

// 

//SYSPRINT DD 
//SYSUT2 DD 



JOB 09#770, SMITH 
EXEC PGM=IEBUPDTE,PARM=NEW 
SYSOUT=A 

DSNAME=OUTLIB , UNIT=23 1 4 , DISP=( NEW , KEEP ) , 
// V0LUME=SER=111112,SPACE=(TRK,{ 100, ,10) ), 
// DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) 
//SYSIN DD DATA 
./ ADD NAME=MEMB1 ,LEVEL=00,SOURCE=0,LIST=ALL 

(Data statements, sequence numbers in columns 73 through 80) 

./ ADD NAME=MEMB2,LEVEL=00,SOURCE=0,LIST=ALL 

(Data statements, sequence numbers in columns 73 through 80) 

./ ADD NAME=MEMB3,LEVEL=00,SOURCE=0,LIST=ALL 

(Data statements, sequence numbers in columns 73 through 80) 

. / ENDUP 

/* 

The control statements are discussed below: 

• SYSUT2 DD defines the new partitioned master OUTLIB. Enough space is allocated 
to allow for subsequent modifications without creating a new master data set. 

• SYSIN DD defines the control data set. The data set contains the utility control 
statements and the data to be placed as three members in the output partitioned 
data set. 

• The ADD Function statements indicate that subsequent Data statements are to be 
placed as members in the output partitioned data set. Each ADD Function 
statement specifies a member name for subsequent data and indicates that the 
member is to be listed in the message data set. 
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• The Data statements contain the data to be placed in the output partitioned data 
set. 

• ENDUP signals the end of control data set input. 

Note: Because sequence numbers (other than blank numbers) are included within the 
data statements, no NUMBER Detail statements are included in the example. 

lEBUPDTE Example 3 In this example, a four-member, partitioned data set (NEWMCLIB) is to be created. 

The data set is to contain: 

• Two members (ATTACH and DETACH) copied from an existing partitioned data set 
(SYSl.MACLIB). 

• One replacement member (BLDL) for an existing member of the input partitioned 
data set. 

• A new member (EXIT) The new member (EXIT) is contained in the control data set. 
The example follows: 

//UPDATE JOB 09#770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 
I //SYSUT1 DD DSNAME=SYS1 .MACLIB,DISP=SHR,UNIT=2314 
I //SYSUT2 DD DSNAME=NEWMCLIB,V0LUME=SER=1 11 112,UNIT=2314, 

// DI SP=( NEW, KEEP ),SPACE=(TRK,( 100, ,10) ), 

// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ) 

//SYS IN DD DATA 

./ REPRO NAME=ATTACH,LEVEL=00,SOURCE=1 ,LIST=ALL 

./ REPRO NAME=DETACH,LEVEL=00,SOURCE=1 ,LIST=ALL 

./ ADD NAME=EXIT,LEVEL=00,SOURCE=1 ,LIST=ALL 

./ NUMBER NEW1=10,INCR=100 

(Data cards for EXIT member) 

. / REPL NAME=BLDL , LEVEL=0 1 , S0URCE=1 , LIST=ALL 
./ NUMBER NEW1=10,INCR=100 

(Data cards to replace BLDL member) 

. / ENDUP 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input partitioned data set SYSl.MACLIB, which is assumed 
to be cataloged. 

o SYSUT2 DD defines the output partitioned data set OUTLIB. Enough space is 
allocated to allow for subsequent modifications without creating a new master data 
set. 

• SYSIN DD defines the control data set. 

• The REPRO Function statements identify the existing input members to be copied 
onto the output data set. These members are also listed in the message data set. 

• The ADD Function statement indicates that records (subsequent Data statements) 
are to be placed as a member in the output partitioned data set. The Data 
statements are to be listed in the message data set. 

• The NUMBER Detail statement assigns sequence numbers to the Data statements. 
(The Data statements contain blank sequence numbers in columns 73 through 80.) 
The first record of the output member is assigned sequence number 10; 
subsequent records are incremented by 100. 

• The REPL Function statement identifies a new member used as a replacement for 
an existing member. The subsequent NUMBER Detail statement assigns sequence 
numbers to the records in the new member. 

• ENDUP signals the end of SYSIN data. 

Note: The three named input members (ATTACH, DETACH, and BLDL) do not have to 
be specified in the order of their collating sequence in the old master. 



lEBUPDTE Program 177 



lEBUPDTE Example 4 



lEBUPDTE Example 5 



In this example, a member (MODMEMB) is to be updated within the space it actually 
occupies. Two existing logical records are to be replaced, and the entire member is to 
be renumbered. 

The example follows: 

//UPDATE JOB 9 # 7 7 , SMI TH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// V0LUME=SER=1 11112 

//SYSIN DD * 

. / CHANGE NAME=MODMEMB , LIST=ALL , UPDATE=INPLACE 

./ NUMBER SEQ1=ALL,NEW1=10,INCR=5 

(Data statement 1, sequence number 00000020) 
(Data statement 2, sequence number 00000035) 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the data set that is to be updated in place. (Note that the 
member name need not be specified in the DD statement.) 

• SYSIN DD defines the control data set. 

• The CHANGE Function statement indicates the name of the member to be updated 
and specifies the UPDATE = INPLACE operation. The entire member is to be listed 
in the message data set. 

• The NUMBER Detail statement indicates that the entire member is to be 
renumbered, and specifies the first sequence number to be assigned and the 
increment value for successive sequence numbers. 

• The Data statements replace existing logical records having sequence numbers of 
20 and 35. 

In this example, a sequential master data set is to be created from partitioned input 
and selected logical records are to be deleted. 

The example follows: 



//UPDATE JOB 
// EXEC 

//SYSPRINT DD 
//SYSUTl DD 
// VOLUME=SER 
//SYSUT2 DD 



09#770, SMITH 
PGM= lEBUPDTE , PARM=MOD 
SYSOUT=A 

DSNAME=PARTDS,UNIT=3330,DISP=(SHR,KEEP), 
111112 

DSNAME=SEQDS , UNIT=2400 , LABEL=( 2 , SL) , 



// DISP=( ,KEEP),VOLUME=SER=001234 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000) 

//SYSIN DD * 

. / CHANGE NEW=PS , NAME=OLDMEMB 1 

(Data statement 1, sequence number 00000123) 

./ DELETE SEQ1=223,SEQ2=246 

(Data statement 2, sequence number 00000224) 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input partitioned data set PARTDS. Because no DCB 
parameters are specified in the SYSUTl DD statement, the input data set is 
assumed to consist of 80-byte, unblocked records. A warning message is issued to 
inform the user that this assumption was made. 

• SYSUT2 DD defines the output sequential data set. The data set is to be written as 
the second data set on a 9-track tape volume. The data set is written at 800 bits 
per inch density. 

• SYSIN DD defines the control data set. 

• CHANGE identifies the input member (OLDMEMBl) and indicates that the output is 
to be a sequential data set (NEW = PS). 

• The first Data statement replaces the logical record whose sequence number is 
identical to the sequence number in the Data statement (00000123). If no such 
logical record exists, the Data statement is incorporated in the proper sequence 
within the output data set. 

• The DELETE Detail statement deletes logical records having sequence numbers 
from 223 through 246. 
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• The second Data statement is inserted in the proper sequence in the output data 
set. 

Note: Only one member can be used as input when converting to sequential 
organization. 

lEBUPDTE Example 6 In this example, a member of a partitioned data set is to be created from sequential 

input and existing logical records are to be updated. 

The example follows: 

//UPDATE JOB 09#770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSEQDS,UNIT=2400,LABEL=( ,SL)', 

// DISP=( OLD , KEEP ) , VOLUME=SER=00 1 234 

//SYSUT2 DD DSNAME=NEWPART,UNIT=2314,DISP=( ,KEEP), 

// VOLUME=SER=111112,SPACE=(TRK,(20,5,5) ), 

// DCB=( RECFM=F , LRECL=80 , BLKSIZE=80 ) 

//SYSIN DD * 

. / CHANGE NEW=PO , MEMBER=PARMEM 1 , LEVEL=0 1 , UC 

./ SEQFLD=605,COLUMN=40,SOURCE=0 

(Data statement 1, sequence number 00020) 

./ DELETE SEQ1=220,SEQ2=250 

I (Data statement 2, sequence number 00230) 
(Data statement 3, sequence number 00260) 

./ ALIAS NAME=MEMB1 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the input sequential data set (OLDSEQDS). The data set was 
originally written at a density of 800 bits per inch on a 9-track tape volume. 

• SYSUT2 DD defines the output partitioned data set. Enough space is allocated to 
provide for members that might be added in subsequent job steps. 

• SYSIN DD defines the control data set. 

• The CHANGE Function statement identifies the output member and indicates that a 
conversion from sequential input to partitioned output is to be made. The SEQFLD 
parameter indicates that a five-byte sequence number is located in columns 60 
through 64 of each Data statement. The COLUMN parameter specifies the starting 
column of a field (within subsequent data statements) from which replacement 
information is obtained. 

• The first Data statement is used as replacement data. Columns 40 through 80 of 
the statement replace columns 40 through 80 of the corresponding logical record. 
If no such logical record exists, the entire card image is inserted in the output 
member. 

• The DELETE Detail statement deletes all of the logical records having sequence 
numbers from 220 through 250. 

e The second Data statement, whose sequence number falls within the range 
specified in the DELETE Detail statement, is incorporated in its entirety in the 
output member. 

• The third Data statement, which is beyond the range of the DELETE Detail 
statement, is treated in the same manner as the first Data statement. 

• ALIAS assigns the alias MEMBl to the output member PARMEMl. 
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In this example, a block of three logical records is to be inserted into an existing 
member, and the updated member is to be placed in the existing partitioned data set. 

Figure 40 shows existing sequence numbers, new sequence numbers, and Data 
statements to be inserted. 



Sequence Numbers and 






Data Statements to be 






inserted 


New Se 


)quenc 


10 




10 


15 




15 


Data statement 1 




20 


Data statement 2 




25 


Data statement 3 




30 


20 




35 


25 




40 


30 




45 



Figure 40. Sequence Numbers and Data Statements to Be Inserted 

The example follows: 

//UPDATE JOB 09#770,SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// V0LUME=SER=1 11112 

//SYSUT2 DD DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// VOLUME=SER= 111112 

//SYSIN DD * 

./ CHANGE NAME=RENUM,LIST=ALL,LEVEL=01 ,SOURCE=0 

./ NUMBER SEQ1=15,NEW1=20,INCR=5,INSERT=YES 

(Data statement 1) 
(Data statement 2) 
(Data statement 3) 

/* 

The control statements are discussed below: 

• SYSUTl and SYSUT2 DD define the partitioned data set PDS. 

• SYSIN DD defines the control data set. 

• The CHANGE Function statement identifies the input member RENUM. The entire 
member is to be listed in the message data set. 

• The NUMBER Detail statement specifies the insert operation and controls the 
renumbering operation. 

• The Data statements are the logical records to be inserted. (Sequence numbers are 
assigned when the Data statements are inserted.) 

In this example, the existing logical records have sequence numbers 10, 15, 20, 25, 
30, etc. Sequence numbers are assigned by the NUMBER Detail statement, as follows: 

1. Data statement 1 is assigned sequence number 20 (NEWl = 20) and inserted after 
existing logical record 15 (SEQl = 15). 

2. Data statements 2 and 3 are assigned sequence numbers 25 and 30 (INCR = 5) 
and are inserted after Data statement 1. 

3. Existing logical records 20, 25, and 30 are assigned sequence numbers 35, 40, and 
45, respectively. 

4. The remaining logical records in the member are renumbered. 
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lEBUPDTE Example 8 In this example, two blocks (three logical records per block) are to be inserted into an 

existing member, and the member is to be placed in the existing partitioned data set. 
A portion of the output member is to be renumbered. 

Figure 41 shows existing sequence numbers, new sequence numbers, and Data 
statements to be inserted. 

Sequence Numbers and 

Data Statements to be 

inserted New Sequence Numbers 

10 10 

15 15 

Data statement 1 20 

Data statement 2 25 

Data statement 3 30 

20 35 

25 40 

30 45 

Data statement 4 50 

Data statement 5 55 

Data statement 6 60 

35 65 

Data statement 7 70 

40 75 

50 80 

150 150 

155 155 

Figure 41. Sequence Numbers and Seven Data Statements to Be Inserted 

The example follows: 

//UPDATE JOB 09 #770, SMITH 

// EXEC PGM=IEBUPDTE,PARM=MOD 

//SYSPRINT DO SYSOUT=A 

//SYSUT1 DO DSNAME=PDS,UNIT=2314,DISP=(OLD,KEEP), 

// V0LUME=SER=1 11112 

//SYSUT2 DO DSNAME=PDS,UNIT=2314,DISP=( OLD, KEEP), 

// V0LUME=SER=1 11112, 

//SYSIN DO * 

. / CHANGE NAME=RENUM , LIST=ALL , LEVEL=0 1 , SOURCE=0 

./ NUMBER SEQ1=15,NEW1=20,INCR=5,INSERT=YES 

(Data statement 1) 
(Data statement 2) 
(Data statement 3) 

./ NUMBER SEQ1=30,INSERT=YES 

(Data statement 4) 
(Data statement 5) 
(Data statement 6) 
(Data statement 7, sequence number 00000038) 

/* 

The control statements are discussed below: 

• SYSUTl and SYSUT2 DD define the partitioned data set PDS. 

• SYSIN DD defines the control data set. 

• The CHANGE Function statement identifies the input member RENUM. The entire 
member is to be listed in the message data set. 

• The NUMBER Detail statements specify the insert operations (INSERT = YES) and 
control the renumbering operation. 

• Data statements 1, 2, 3, and 4, 5, 6 are the blocks of logical records to be 
inserted. Because they contain blank sequence numbers, sequence numbers are 
assigned- when the Data statements are inserted. 

• Data statement 7 is a logical record to be inserted in the output member. 

The existing logical records in this example have sequence numbers 10, 15, 20, 25, 
30, 35, 40, 45, 50, 150, 155, 160, 165, etc. The insert and renumbering operations 
are performed as follows: 

1. Data statement 1 is assigned sequence number 20 (NEWl = 20) and inserted after 
existing logical record 15 (SEQl = 15). 
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2. Data statements 2 and 3 are assigned sequence numbers 25 and 30 (INCR = 5) 
and are inserted after data statement 1. 

3. Existing logical records 20, 25, and 30 are assigned sequence numbers 35, 40, and 
45, respectively. 

4. Data statement 4 is assigned sequence number 50 and inserted. (The SEQl = 30 
specification in the second NUMBER statement places this data statement after 
existing logical record 30, which has become logical record 45.) 

5. Data statements 5 and 6 are assigned sequence numbers 55 and 60 and are 
inserted after Data statement 4. 

6. Existing logical record 35 is assigned sequence number 65. 

7. Data statement 7 is assigned sequence number 70 and is inserted. 

8. The remaining logical records in the member are renumbered until logical record 
150 is encountered. Because this record has a sequence number higher than the 
next number to be assigned, the renumbering operation is terminated. 

In this example, lEBUPDTE is used to create a sequential data set from card input. 
User header and trailer labels, also from the input stream, are placed on this 
sequential data set. 

The example follows: 

//LABEL JOB , MSGLEVEL= 1 

//CREATION EXEC PGM=IEBUPDTE, PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=LABEL,V0LUME=SER=1 23456, 

// DISP=( NEW, KEEP ), LABEL=( ,SUL), 

// SPACE=(TRK,( 15,3) ),UNIT=2314 

//SYSIN DD * 



LIST=ALL , 0UTHDR=R0UTINE 1 , 0UTTLR=R0UTINE2 



. / LABEL 


(First header label) 


(Last header label) 
./ ADD 


(First input data record) 


(Last input data record) 


. / LABEL 


(First trailer label) 
(Last trailer label) 


. / ENDUP 
/* 



The control statements are discussed below: 

• SYSUT2 DD defines and allocates space for the output sequential data set, which 
resides on a 2314 volume. 

• SYSIN DD defines the control data set. (This control data set includes the 
sequential input data set and the user labels, which are on cards.) 

• The first LABEL statement identifies the 80-byte card images in the input stream 
which will become user header labels. (They can be modified by the user's header 
label processing routine specified on the ADD Function statement.) 

• The ADD Function statement indicates that the Data statements that follow are to 
be placed in the output data set. The newly created data set is to be listed in the 
message data set. User output header and output trailer routines are to be given 
control prior to the writing of header and trailer labels. 

• The second LABEL statement identifies the 80-byte card images in the input 
stream which will become user trailer labels. (They can be modified by the user's 
trailer label processing routine specified on the ADD Function statement.) 

• ENDUP signals the end of the control data set. 
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lEBUPDTE Example 10 In this example, lEBUPDTE is used to copy a sequential data set from one 

direct-access volume to another. User labels are processed by user exit routines. 

The example follows: 

//LABELS JOB ,MSGLEVEL=1 

// EXEC PGM=IEBUPDTE,PARM=(MOD, ,MMMMMM) 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDMAST,DISP=OLD,LABEL=( ,SUL), 

// V0LUME=SER=1 11111 ,UNIT=2314 

//SYSUT2 DD DSNAME=NEWMAST, DISP=( NEW, KEEP ), LABEL= ( ,SUL), 

// UNIT=2314,VOLUME=SER=XB182. 

// SPACE=( TRK, (10,10)) 

//SYSIN DD DSNAME=INPUT,DISP=OLD,LABEL=( ,SUL), 

// VOLUME=SER=222222,UNIT=2314 

/* 

(Input data set) 

./ REPRO LIST=ALL,INHDR=SSSSSS,INTLR=TTTTTT, «C 

./ OUTHDR=XXXXXX,OUTTLR=YYYYYY 

. / ENDUP 

The control statements are discussed below: 

• SYSUTl DD defines the input sequential data set, which resides on a 2314 volume. 

• SYSUT2 DD defines the output sequential data set, which will reside on a 2314 
volume. 

• SYSIN DD defines the control data set. 

• The REPRO Function statement indicates that the existing input sequential data set 
is to be copied to the output data set. This output data set is to be listed on the 
message data set. The user's label-processing routines are to be given control 
when header or trailer labels are encountered on either the input or the output data 
set. 

• ENDUP indicates the end of the control data set. 
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lEHATLAS Is a system utility used when a defective track is indicated by a data check 
or missing address marker condition. (See "Introduction" for general system utility 
information.) 

lEHATLAS can be used to locate and assign an alternate track to replace the defective 
track. Usable data records on the defective track are retrieved and transferred to the 
alternate track. The bad record from the defective track is then replaced on the 
alternate by a correct copy provided by the user. 

In a simple application, lEHATLAS is used as a separate job after an abnormal 
termination of a problem program. Input data necessary for execution of 
lEHATLAS — the address of the defective track and replacement records — may be 
obtained from the dump and from backup data. 

A more complex use of lEHATLAS may involve the preparation of a user's SYNAD 
routine, which reconstructs the necessary input data and invokes lEHATLAS 
dynamically. 

When lEHATLAS is invoked, it attempts to write on the defective track. If the 
subsequent read-back check indicates that the attempt was successful, a message is 
issued on the SYSOUT device. If not, a supervisor call routine (SVC 86) is entered 
automatically. 

The SVC routine locates and assigns an alternate track. (If a defective track already 
has an alternate and an error occurs on that alternate, the SVC routine assigns the 
next available alternate. All of the valid data records on the defective track are 
retrieved and transferred to the alternate track. The input record is written on the 
alternate track in the correct position to recover from the previous error. 

When a READ error occurs and a complete recovery is desired, lEHDASDR can be 
used to produce a listing of error data on a track. Using this data, the input data 
record for lEHATLAS can be created. The replace function can then be performed by 
executing lEHATLAS. 

The direct access device types supported by lEHATLAS are 2302, 2311, 2314, 2319, 
2305, and 3330. 

lEHATLAS uses the following input: (1) a description of the defective track, specifying 
the bin (or cell), cylinder, track, record, key, and data length (in hexadecimal 
notation), (2) an indication if WRITE Special is needed, and (3) a valid copy (in 
hexadecimal notation) of the bad record. 

lEHATLAS produces as output: (1) a message, issued on the SYSOUT device, 
containing the user's control information, the input record, and diagnostics, (2) the 
input record, written on either the original (defective) track or on an alternate track 
containing the usable data taken from the defective track, and (3) the return 
parameter list (specifying a maximum of three error record numbers in hexadecimal 
when an unrecoverable error occurs). 

lEHATLAS is controlled by job control statements and utility control statements. The 
job control statements are used to execute or invoke lEHATLAS and to define the data 
sets used and produced by lEHATLAS. 

A utility control statement is used to specify whether the bad record is a member of 
the volume table of contents or a member of some other data set. It is also used to 
indicate whether or not the WRITE Special command is to be used. 

Table 34 shows the job control statements necessary for using lEHATLAS. 

For detailed information on the minimum region size that can be specified for 
lEHATLAS, see OS Storage Estimates, GC28-6551. 

• The block size for the SYSPRINT data set must be a multiple of 121. The block size 
for the SYSIN data set must be a multiple of 80. Any blocking factor can be 
specified. 

• DISP = SHR must not be coded on the SYSUTl DD statement. 
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Table 34. lEHATLAS Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies tlie program name (PGIVI = lEHATLAS) or, if the job control statements 

reside in a procedure library, the procedure name. 

SYSABEND DD Defines a dump data set. It must include appropriate parameters for a basic 
sequential (BSAM) data set. The data set can be written to a system output 
device, a tape volume, or a direct access volume. 

SYSPRINT DD Defines a sequential data set that contains the output messages issued by 
lEHATLAS. 

SYSUTl DD Defines the data set that contains the bad record. 

SYSIN DD Defines the control data set, which contains the utility control statement and a 

copy of the bad record. 

The TRACK or VTOC control statement is used to control lEHATLAS. 

The TRACK or VTOC statement is used to identify the defective record. 

The format of the TRACK or VTOC statement is: 

{TRACK = bbbbcccchhhhrrkkdddd[S] } 
{VTOC = bbbbcccchhhhrrkkdddd } 

where: 

TRACK = 

specifies that an alternate track is to be assigned for a track that does not contain 
VTOC records. 

VTOC = 

specifies that an alternate track is to be assigned for a track that contains VTOC 
records. 

bbbb 

is the bin (or cell) number when the device specified in the SYSUTl DD Statement 
is a 2321 data cell; if the device is other than a 2321 data cell, the number must 
be padded with zeros. 

cccc 

is the number of the cylinder in which the defective track was found. 

hhhh 

is the defective track number. 

rrkk 

is the record number and key length for the bad record. 

dddd 

is the data length of the bad record. (When a WRITE Special command is used, 
dddd is the length of the record segment. 

S 

is an optional byte of EBCDIC information that specifies that the WRITE Special 
command is to be used (when the last record on the track overflows and must be 
completed elsewhere). 

Care should be taken to ensure that the input record data length does not exceed the 
track size. This is especially important when the WRITE Special command is specified 
because the error may not be recognized immediately by the system. 

The TRACK or VTOC statement must not begin in column 1. 

Input data (consisting of the hexadecimal replacement record) begins in column 1 
immediately following the utility control data. Input data may continue through column 
80. As many cards as necessary may be used to contain the replacement record. All 
columns (1 through 80) are used on the additional cards. 

lEHATLAS is designed to replace an error record with a copy of that record. It cannot 
be used to replace a record with another of a different key and/or data length. 

An end-of-file record cannot be changed; therefore, input for key and/or data fields 
are ignored. 
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lEHATLAS Examples 



The following examples Illustrate some of the uses of lEHATLAS. Table 35 can be used 
as a quick reference guide to lEHATLAS examples. The numbers in the "Example" 
column point to examples that follow. 
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Table 35. lEHATLAS Example Directory 

Operation Comments 

Get Alternate Write Special is included because of a 

Tracks track overflow condition. 

Get Alternate Alternate track assigned for a bad 

Track end-of-file record. 

Get Alternate Alternate track assigned for a bad 

Track VTOC record. 

Get Alternate Replace defective record zero. 
Track 



Example 

1 
2 
3 
4 



In this example, the data set defined by SYSUTl contains the bad record. An alternate 
track on the specified unit and volume will be assigned to replace the defective track. 

The example follows: 

//JOBATLAS JOB 06 #990 , SMITH, MSGLEVEL=1 

//STEP EXEC PGM=IEHATLAS 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=NEWSET,UNIT=3330,VOLUME=SER=333011 , 

// DISP=OLD 

//SYSIN DD * 

TRACK=00000002000422020006S 
F3F1C2C2F0F00000 
/* 

The control statements are discussed below: 

• SYSPRINT DD defines the device to which the output messages can be written. 

• SYSUTl DD defines the data set that contains the bad record. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• TRACK specifies the bin, cylinder, and track number for the defective track; and 
the record number, key length, and data length of the bad record. In this example, 
the device is a 3330, so the input record has a bin number of zero; the record is to 
be placed on cylinder 2, track 4, record 22; and it has a key length of 2 with a 
logical record length of 8. The WRITE Special (S) character is used because there is 
a track overflow condition. 

The input record is a typical hexadecimal record as defined by the TRACK statement. 
The input record contains eight bytes (data length = 6, key length = 2). 

In this example, an alternate track is assigned for a bad end-of-file record. 

The example follows: 

//JOBATLAS JOB 06#990 , SMITH, MSGLEVEL=1 

//STEP EXEC PGM= lEHATLAS 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSNAME=EOFSET,UNIT=2305,VOLUME=SER=333333, 

// DISP=OLD 

//SYSIN DD * 

TRACK=00000001 000003000000 
/* 

The control statements are discussed below: 

• SYSPRINT DD defines the device to which the output messages can be written. 

• SYSUTl DD defines the data set that contains the bad record. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• TRACK defines an end-of-file record on cylinder one, track zero, record three. 
Input data other than the utility control statement is not required. 
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In this example, an alternate track Is assigned for a bad VTOC record. 
The example follows: 



//JOBTALAS JOB 06# 990 , SMITH, MSGLEVEL=1 

//STEP EXEC PGM=IEHATLAS 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=3330,VOLUME=SER=222222,DISP=OLD 

//SYSIN DD * 

VTOC=000000000005022C0060 
D6C2D1C5C3E340404040404040404040404040404040404040404040404040404040404040404040 
a0404040F1F2F3FlFlF0F00001 4401 36000000010000000000000000000000000000000000000000 
000040008000000FOOOF00033333333333333333310DDD00000100000AOOOOOOOAOOOOOOOOOOOOOO 
0000000000000000000000000000000000000000 

/* 

The control statements are discussed below: 

• SYSPRINT DD defines the device to which the output messages can be written. 

• SYSUTl DD defines the data set that contains the bad record. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• VTOC defines the location of the bad VTOC record as track five of cylinder zero. 
The record number is 2 with a key length of 44. Record length of the bad record is 
96. 

The input record in this example is a typical hexadecimal record as defined by the 
VTOC statement. The input record contains 140 bytes (data length = 96, key 
length = 44). 

In this example, the replacement record is record zero. 

The example follows: 
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06#990 , SMITH , MSGLEVEL= 1 

PGM=IEHATLAS 

SYSOUT=A 

DSNAME=NEWSET,UNIT=3330,VOLUME=SER=333001 , 



//JOBATLAS JOB 
//STEP EXEC 
//SYSPRINT DD 
//SYSUTl DD 
// DISP=OLD 
//SYSIN DD * 

TRACK=00000002000400000008 
0000000000000000 
/* 

The control statements are discussed below: 

• SYSPRINT DD defines the device to which the output messages can be written. 

• SYSUTl DD defines the data set that contains the bad record. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• TRACK specifies the bin, cylinder, and track number for the defective track; and 
the record number, key length, and data length of the bad record. In this example, 
the device is a 3330, so the input record has a bin number of zero; the record is to 
be placed on cylinder 2, track 4, record 0; and it has a key length of zero with a 
logical record length of 8. 

The input record is a typical hexadecimal record as defined by the TRACK statement. 
The input record contains eight bytes (data length = 8, key length = 0). 
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lEHDASDR is a system utility used to prepare direct access volumes for operating 
system use and to ensure that any permanent hardware errors (that is, defective 
tracks) incurred on direct access volumes do not seriously degrade the performance 
of those volumes. (See "Introduction" for general system utility information.) 

In addition, lEHDASDR can be used to dump the entire contents or portions of a direct 
access volume to a volume or volumes of the same direct access device type, to a 
tape volume or volumes, or to a system output device. Data that is dumped to a 
magnetic tape volume is arranged so that it can subsequently be restored to its 
original organization by lEHDASDR. The direct access device types supported by 
lEHDASDR are: 2301, 2302, 2303, 2305, 2311, 2314, 2319, 2321, and 3330. 

The program can be used to: 

• Analyze tracks, assign alternate tracks for defective tracks, and perform 
housekeeping and formatting functions to make direct access volumes suitable for 
IBM System/360 Operating System use. 

Note: Defective tracks are flagged when the 3330 disk storage volumes are initialized 
at the factory. An lEHDASDR job to initialize a 3330 does not perform a surface 
analysis. The ANALYZE option performs a "quick-DASDI" which includes: 

1. Initialization of track zero, including IPLl, IPL2, volume label, and optional 
IPLTXT. 

2. VTOC construction. 

• Perform housekeeping and formatting functions on direct access volumes without 
analyzing tracks. 

• Change the volume serial number of a formatted direct access volume. 

• Assign alternate tracks for specified defective or questionable tracks on disk or 
data cell volumes. 

• Create a backup or transportable copy of a direct access volume, or list the 
contents on a system output device. 

• Copy dumped data from a tape volume to a direct access volume. 

lEHDASDR can be used to analyze the recording surface of a direct access device 
to: 

• Assign alternate tracks for any disk or data cell tracks found defective during an 
analysis, or for any track previously flagged defective. Each track can be analyzed 
from 1 to 255 times, at the discretion of the user. The test of looking for previously 
flagged tracks must be suppressed when a new or unformatted direct access 
volume is being initialized. 

• Standardize each track by placing a standard home address and a record zero (RO) 
field on it. The remainder of the track is erased. 

• Construct IPL bootstrap records (records 1 and 2 of track 0), a volume label record 
(record 3 of track 0), and a volume table of contents (VTOC), whose size and 
placement are determined by the user. 

• Provide owner information in the volume label record. 

Figure 42 shows a direct access volume after it has been prepared for IBM 
System/360 Operating System use. A direct access volume can be initialized in this 
manner using lEHDASDR. 

lEHDASDR can be used to prepare a direct access volume for use without 
performing a recording-surface analysis. 

A volume might be prepared for system use without recording-surface analysis to: 

• Check a direct access volume for previously flagged tracks (except for drum 
volumes). No formatting is performed on known defective tracks. 

• Standardize each track by placing a standard home address and a record zero (RO) 
field on it. The remainder of the track is erased (except on 3330 volumes). 

• Construct IPL bootstrap records (records 1 and 2 of track 0), a volume label record 
(record 3 of track 0), and a volume table of contents (VTOC), whose size and 
placement are determined by the user. 
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Figure 42. Direct Access Volume Initialized Using lEHDASDR 

• Optionally write an IPL program record for 2301, 2303, 2305, 2311, 2314, 2319, 
and 3330 devices, and provide owner information in the volume label record. 

lEHDASDR can be used to change the volume serial number of an initialized 
direct access volume. Optionally, a one- to ten-character owner name can be 
placed in the volume label record (record 3 of track 0). If an owner name already 
exists, it is overwritten with the new name. 

Note: All cataloged data sets residing on a volume whose label is changed must be 
recataloged, if the catalog reflects the old serial number. 

lEHDASDR can be used to assign an alternate track on a data cell or disk volume. 
An alternate track can be assigned for any track, whether it is defective or not. If the 
specified track is an alternate, a new alternate is assigned; if the specified track is an 
unassigned alternate, it is flagged to prevent its future use. 

Note: If it is necessary to assign an alternate track on a drum volume, an IBM 
Programming Service Representative should be notified. 

lEHDASDR can be used to dump a direct access volume or a portion of a volume to 
any number of tape volumes or volumes of the same direct access device type, or 
to a system output device. The program can dump a single track, a group of tracks, or 
an entire volume. 

When an entire volume is dumped: 

• All primary tracks (for which no alternate tracks are assigned) are dumped. 

• When a primary track is found to have an alternate track assigned, the alternate is 
dumped in place of the primary. 

Each track to be dumped will have all of its data except the home address and the 
count field of record zero (RO) copied to the receiving volume. 

A receiving direct access volume retains its own serial number unless the user 
specifies that it is to be assigned the serial number of the direct access volume being 
dumped. 

Except for a printing operation, only data that is owned is dumped; lEHDASDR checks 
the first or only Free Space (Format 5) data set control block (DSCB) in the volume 
table of contents. The Free Space (Format 5) DSCB identifies unowned (unused) 
space on the direct access volume. Whenever an unowned track is encountered, a 
dummy record, containing a home address and record zero, is written on the receiving 
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volume. When data is dumped to a system output device, the entire range of specified 
tracks is dumped. 

A printing operation prints each record in hexadecimal, in addition, all printable 
characters are also represented in EBCDIC. 

Figure 43 shows the format of printed output. Each track is identified by its absolute 
track address (cccchhhh). The RO data field is printed on the same line as the track 
address. Each printed record is preceded by a count field that identifies the applicable 
track address (cccchhhh), the record number of the record being printed (rr), and the 
key and data length (kk and dddd) of the record. 



TRACK cccchhhh 



RO DATA XX 



xxxxxxxxxxx 



COUNT cccchhhhrrkkdddd 

key and data fields key and data fields 

(hexadecimal) (EBCDIC) 

000000 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx • • 

000032 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx • • 

etc. 

COUNT cccchhhhrrkkdddd 

000000 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx • • 

000032 xxxxxxxx xxxxxxxx xxxxxxxx etc. 

••• TRACK cccchhhh RO DAJA xxxxxxxxxxxxxxxx 

COUNT cccchhhhrrkkdddd 

000000 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx • * 

000032 xxxxxxxx xxxxxxxx etc. 



Copying Dumped Data 
to a Direct Access 
Volume 



Input and Output 



Figure 43. Format of a Direct Access Volume Dumped to a Printer Using lEHDASDR 

If an alternate track is printed in place of a primary track, it is identified in the printout 
by the primary track address. 

When a direct access volume is dumped to a tape volume, the data is placed in a 
format that is specially suited for the tape volume. lEHDASDR can be used to restore 
the format of the dumped data and place the data on the same type of direct access 
volume as the original volume; that is, data originally dumped from a 2311 volume can 
be restored to a 2311 volume, data dumped from a 2314 volume can be restored to a 
2314 volume. 

Identical copies of dumped data can be restored to any number of volumes of the 
same direct access device type as the original volume during the execution of a single 
restore operation. In addition, data that was dumped by IBCDMPRS can be restored. 

A receiving direct access volume retains its own serial number unless the user 
specifies that it is to be assigned the serial number of the direct access volume 
originally dumped. If multiple direct access volumes are to be dumped to, and the user 
specifies that the serial number of the dumped volume is to be propagated, all 
receiving volumes are assigned that serial number. 

lEHDASDR uses as input a control data set containing utility control statements and, 
optionally, IPL text. 

The primary output or result of executing lEHDASDR is determined by the application. 

A sequential message data set is created to list informational messages (for example, 
control statements used), dumped data (for a print operation), and any error 
messages. 

lEHDASDR provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that an unusual condition was encountered; however, the 
overall result is successful. A warning message is issued. 

• 08, which indicates that a specified operation did not complete successfully. An 
attempt is made to perform any additional operations. 

• 16, which indicates that either an error occurred upon invoking lEHDASDR, or 
lEHDASDR was unable to open the input or message data set. The job step is 
terminated. 
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lEHDASDR is controlled by job control statements and utility control statements. The 
job control statements are used to execute or invoke lEHDASDR and define the data 
sets used and produced by lEHDASDR. 

The utility control statements are used to control the functions of the program. 

Table 36 shows the job control statements necessary for using lEHDASDR. 

Table 36. lEHDASDR Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGIVI = lEHDASDR) or, if the job control statements 

reside in a procedure library, the procedure name. Additional information can be 
entered in the PARM parameter of the EXEC statement; see "FARM Information 
on the EXEC Statement" below. 

SYSPRINT DD Defines a sequential message data set. The data set can be written to a system 
output device, a tape volume, or a direct access device. 

anyname DD Defines a direct access device type. 

tapename DD Defines a magnetic tape drive. 

SYSIN DD Defines the control data set. The control data set usually resides in the input 

stream; however, it can be defined as a blocked or unblocked sequential data set 
or as a member of a procedure library. 

For detailed information on the minimum region size that can be specified for 
lEHDASDR, see OS Storage Estimates, GC28-6551. 

The "anyname" DD statement can be entered: 

//anyname DD UNIT = xxxx,VOLUME = SER = xxxxxx,DISP = OLD 

If more than one volume is to be processed on a single mountable device, deferred 
mounting can be specified in the "anyname" DD statement by entering: 

//anyname DD UNIT = (xxxx„DEFER),VOLUME = (PRIVATE,...), 
// DISP = (OLD,KEEP) 

The "anyname" DD statement is not used for an operation that analyzes an offline 
direct access volume. 

If the volume serial number of a volume to be processed on line is not known, it may 
be possible to make a nonspecific, PRIVATE volume request on a specific unit; for 
example: 

//anyname DD UNIT = (191„DEFER),V0LUME = PRIVATE.DISP = (NEW,KEEP), 
// SPACE = (TRK,( 1,1)) 

In this case, the operator is asked to mount a scratch volume on that unit. See 
"Appendix C: Defining Mountable Devices" for the appropriate DD statement and for 
a discussion of how to make a nonspecific unit request. 

If an lEHDASDR operation produces a volume serial number that is a duplicate of a 
volume serial number already allocated within the system, the volume to which the 
duplicate number is assigned is made unavailable to the system. The operator is asked 
to remove the applicable volume at the completion of the operation. 

The "tapename" DD statement can be entered: 

//tapename DD UNIT = xxxx, VOLUME = SER = xxxxxx,LABEL = ( ), 

// DISP = (...,KEEP),DCB = (TRTCH = C,DEN = x) 

If more than one tape volume is to be processed on the same tape drive, deferred 
mounting can be specified by: 

//tapename DD UNIT = (xxxx„DEFER),VOLUME = (PRIVATE,...) 

If standard labeled tapes are specified, the DSNAME should also be provided. 

The "anyname" DD and "tapename" DD statements are referred to by utility control 
statements for program operation. 

Both the SYSIN and the SYSPRINT data set can have a blocking factor of other than 1. 

Data can be dumped from the system residence volume (the IPL volume); however, 
this is the only lEHDASDR operation that can be performed on that volume. 
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Because lEHDASDR can change serial numbers and existing data on a direct access 
volume, operating precautions must be followed by users who have two or more 
central processing units sharing the same direct access volume. 

If lEHDASDR is run in a multiprogramming environment, the user must choose a 
combination of DD statements (defining mountable devices) that will ensure that 
volume integrity is maintained. Refer to "Appendix C: DD Statements for Defining 
Mountable Devices." 

If password-protected data sets reside on volumes that are used by lEHDASDR, the 
following considerations must be made: 

• When dumping from a volume containing password-protected data sets, each data 
set must be described in a separate DD statement having a unique ddname. When 
the program is executed, the operator must supply the correct password (in answer 
to a console message) for each password-protected data set. 

• When dumping to a tape volume from a direct access volume containing 
password-protected data sets, the DD statement defining the tape volume must 
include a DSNAME parameter. In addition, the LABEL parameter must define a 
standard labeled tape, include a PASSWORD subparameter, and specify or imply a 
file number of 1. 

• When restoring from a tape volume, a DSNAME parameter must be included in the 
DD statement defining the tape volume. 

• During the DUMP, RESTORE, ANALYZE, and FORMAT functions (see "Utility 
Control Statements"), the direct access "TO" volume is checked for 
password-protected data sets. At this time the operator must supply the correct 
password for each password -protected data set encountered. 

Refer to OS Data Management for System Programmers, GC28-6550, for additional 
information on password protection. 

lEHDASDR can perform up to six concurrent operations of ANALYZE, FORMAT, DUMP 
or RESTORE operations (see "Utility Control Statements"). This feature, which can 
shorten the time required to execute the program, is controlled by (1) the number of 
devices defined for use and (2) the physical arrangement of utility control statements 
in the input stream. For example, assuming thai the required devices are defined and 
available, a combination of six successive statements of the same type permits six 
concurrent operations to take place. However, if the utility control statements are 
arranged so that no operations of the same type appear in succession, no operations 
are performed concurrently, even though many devices might be defined for use. 

Note: The number of concurrent operations allowed can be overridden by an EXEC 
statement FARM value. 

• If lEHDASDR is used to change a volume serial number and a subsequent operation 
is performed on the newly labeled volume in the same job step, two "anyname" DD 
statements are required. The VOLUME parameter in the first statement includes the 
old volume serial number; the VOLUME parameter in the second statement 
specifies the new volume serial number. In addition, the second statement specifies 
unit affinity with the first. 

• One "anyname" DD statement is required for each device to be used in the job 
step unless the device is to be processed off line. 

• The "tapename" DD statement must be included if a data set is dumped to tape or 
if a previously dumped data set is to be restored to a direct access volume. 

• If BLKSIZE is specified on the SYSIN DD statement, it must be a multiple of 80. If 
BLKSIZE is omitted from the statement, a block size of 80 bytes is assumed. 

• If BLKSIZE is specified on the SYSPRINT DD statement, it must be a multiple of 
121. If BLKSIZE is omitted or incorrectly specified, a block size of 121 bytes is 
assumed. 

• SYSIN attributes must be identical if SYSIN data sets are to be concatenated. 

The EXEC statement for lEHDASDR can contain PARM information that is used by 
the program to control line density on output listings and to indicate the maximum 
number of operations of the same type that can be performed concurrently in the job 
step. 

The EXEC statement can be coded: 



// EXEC PGM = lEHDASDR 



{,PARM = *N = n' } 

{,PARM = 'LINECNT = xx' } 

{,PARM = 'LINECNT = xx,N = n' } 
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utility Control Statements 



ANALYZE Statement 



The LINECNT value specifies the number of lines per page in the listing of the 
SYSPRINT data set. The number xx is a 2-digit decimal number ranging from 01 to 99. 
If LINECNT is omitted, the number of lines per page is 58. 

The N value specifies a decimal number from one to six that represents the maximum 
number of like functions that can be performed concurrently by lEHDASDR, assuming 
that adequate system resources are available. See OS Storage Estimates, GC27-6551, 
for the storage required for each operation. If N is omitted, up to six ANALYZE, 
FORMAT, DUMP, or RESTORE operations are performed concurrently — according to 
the number of successive like statements in the input stream. (See "Utility Control 
Statements.") 

System resources permitting, multiple output copies can be specified in any or all of 
the concurrent operations. 

For example, if N = 2 and four DUMP statements appear in succession, the first two 
dump operations are performed concurrently. As each dump operation is completed 
and system resources become available, a new dump operation begins. 

The utility control statements used to control lEHDASDR are: 

• ANALYZE statement, which is used to analyze the recording surface to test for 
defective tracks, assign alternates for any defective tracks found, and to format the 
volume to make it ready for use. 

• FORMAT statement, which is used to make a volume ready for use without 
performing an analysis of the recording surface. 

• LABEL statement, which is used to change the volume serial number of a direct 
access volume and, optionally, to update the owner field. 

• GETALT statement, which is used to assign an alternate track for a specified disk 
track or data cell. 

• DUMP statement, which is used to dump a single track, a group of tracks, or an 
entire direct access volume. 

• RESTORE statement, which is used to restore a previously dumped direct access 
volume to a direct access device. 

• IPLTXT statement, which signals the beginning of IPL program text statements. 

For most operations, multiple copies of a source volume can be made. The program 
can also perform from two to six ANALYZE, FORMAT, DUMP, or RESTORE operations 
concurrently, according to the number of successive like statements in the input 
stream; that is, up to six direct access volumes can be analyzed or formatted, or 
dumped simultaneously, or up to six magnetic tape (restore) volumes can be 
processed simultaneously. 

The ANALYZE statement is used to analyze the recording surface of a direct access 
device. Bit patterns are written on a track, read, and tested for defects. If no defects 
are found, the track is formatted to make it ready for system use. 

The format of the ANALYZE statement is: 

[/abe/] ANALYZE TODD = {(cuu,...) } 

{{ddname,...) } 
,VTOC = xxxxx 
.EXTENT = xxxxx 
[.NEWVOLID = serial] 
[.IPLDD = ddname] 
.FLAGTEST = { YES } 
{NO } 
[.PASSES = {n }] 

{0 } 

[.OWNERID = r)ame] 
[.PURGE = {YES }] 
{NO } 
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where: 

TODD = 

specifies the volume to be processed. If multiple volumes are specified in an 
ANALYZE statement and an abnormal completion of the ANALYZE operation 
occurs, the operation is terminated on all volumes. These values can be coded: 

(cuu,...) 

specifies the channel and unit address of a direct access device containing a 
volume to be initialized. This value is used only for the analysis of a volume off 
line, which includes the first analysis of a volume. If the volume to be processed 
is a 2321 volume, TODD = cuu/b is specified, where cuu is the channel and unit 
address of the device, and b is the bin number of the volume; for example, 
TODD = 150/0 specifies bin with a channel and unit address of 150. If this 
value is coded, no DD statement defining a mountable device is required. When 
this volume is coded, the specified devices must be varied off line (by use of the 
VARY OFFLINE command) prior to the execution of the job step. 

(ddname,...) 

specifies the ddname of a job control statement defining a direct access device 
containing a volume to be analyzed, formatted, and labeled. Multiple ddnames 
specifying additional job control statements can be included unless the TODD 
device is a 2321, in which case only one DD statement can be referred to. 

VTOG = xxxxx 

specifies a one- to five-byte decimal relative track address representing a primary 
track on which the volume table of contents is to begin. The VTOG cannot occupy 
track 0, and it cannot occupy track 1 if IPL text is written for 2303 and 2311 
volumes. 

EXTENT = xxxxx 

specifies the decimal length of the VTOG in tracks. The VTOG cannot extend into 
the alternate track area or onto a second volume. 

NEWVOLID = serial 

specifies a one- to six-character serial number. The serial number is assigned to all 
direct access volumes processed through the use of this control statement. If 
NEWVOLID is omitted, all direct access volumes retain their own serial numbers. 
This parameter is required for the analysis of a volume off line. 

IPLDD = ddname 

specifies the ddname of a DD statement defining the data set containing the IPL 
program. The IPL program can be included in the SYSIN (input stream) data set, or 
it can be defined as a sequential data set or a member of a partitioned data set. If 
IPL text is included in the input stream, an IPLTXT statement is used to separate 
the ANALYZE statement from the IPL program text statements. The maximum IPL 
record size is 3625 bytes. IPLDD applies to 2301, 2303, 2305, 2311, 2314, 2319, 
and 3330 volumes. 

Note: Gaution should be used to ensure that the DD statement being referred to is 
coded correctly. 

FLAGTEST = 

specifies whether a check is to be made for previously flagged tracks. FLAGTEST is 
applicable to disk and data cell volumes, not to drum volumes. When a volume is 
initialized off line, no check is made. These values can be coded: 

YES 

specifes that each track is to be checked to see if it was previously flagged as 
defective. If FLAGTEST is omitted, YES is assumed. 

NO 

specifies that the program is not to check for previously flagged tracks on the 
volume. 

PASSES = 

specifies the number of passes to be made in analyzing a recording surface. These 
values can be coded: 



n 



specifies the number of times a bit pattern test is to be performed. The n value 
is a decimal number from 1 to 255. If PASSES is omitted, the bit pattern test is 
performed once on each track. This value is applicable to disk and drum 
volumes, with the exception of 3330 volumes. 
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specifies that the ANALYZE function is to bypass all surface analysis and track 
formatting, writing only a VTOC, track zero records (IPL bootstrap and volume 
label records), and IPL text if requested. The value applies to all direct access 
volumes supported by lEHDASDR. If the device is a 3330, only the 
specification is allowed, and is forced regardless of the PASSES parameter. This 
value is applicable to all previously initialized direct access devices supported by 
lEHDASDR while on line. The offline "quick-DASDI" feature is only supported for 
2314, 2305, and 3330 volumes. 

OWNERID = name 

specifies a one- to ten-character name or other identifying information to be 
placed in the volume label record. OWNERID is specified as an EBCDIC character 
string with the exclusion of the blank and the comma characters (these terminate 
the control card scan of a field or an entire card). 

PURGE = 

specifies whether the ANALYZE operation is to be terminated when an unexpired 
data set is encountered. If PURGE is omitted, and an unexpired data set is 
encountered, the ANALYZE operation is terminated. These values can be coded: 



YES 



NO 



r 



indicates that all unexpired data sets on the volume can be overwritten provided 
that the operator signals his concurrence when the first unexpired data set is 
encountered. 

) 

specifies that the ANALYZE operation is to be terminated if an unexpired data 
set is encountered. This is the default. 



If PURGE = YES is coded and an unexpired data set is encountered, the operator is 
prompted. The operator replies are: 

• U, which indicates that all unexpired data sets on this volume can be overwritten. 
(The ANALYZE operation continues.) 

• T, which indicates that this volume contains unexpired data sets that must not be 
overwritten. (The ANALYZE operation is terminated.) 

The PURGE parameter does not apply to password-protected data sets; that is, the 
operator must always respond with the proper password for each password-protected 
data set encountered. If he is unable to do so, the ANALYZE operation is terminated. 

Note: If the device is on line and a volume label and VTOC are present, they are read, 
and the information contained in them is used to initialize the volume. If the device is 
off line, the volume label and VTOC are ignored. 

The FORMAT statement is used to prepare a volume for operating system use. Except 
for flag testing, no analysis is made prior to formatting a track. Previously flagged disk 
tracks remain flagged; alternate tracks are assigned, where applicable. Because the 
FORMAT statement does not cause recording-surface analysis, it should not be used 
for the first initialization of a volume. 

Output produced as a result of using the FORMAT statement includes a list of 
defective tracks and their assigned alternates. 

The FORMAT statement is not applicable to the 2321 data cell. The ANALYZE function 
should be used when initializing a 2321 volume. (If FORMAT is specified for a 2321 
volume, the ANALYZE function is automatically performed.) 

Note: If a command reject is detected while a FORMAT operation is performed on an 
assigned alternate track on an IBM 2305 Fixed Head Storage volume, processing 
continues as if no alternate track existed. No action need be taken if message 
IEH4000I is typed out on the operator's console in response to this condition. If 
FORMAT cannot read a home address, it flags the defective track and assigns an 
alternate track. 
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The format of the FORMAT statement is: 

[/abe/] FORMAT TODD = (ddname,...) ; 

,VTOC = xxxxx I 

.EXTENT = xxxxx j 

[.NEWVOUD = ser/a/] 
[,l PLDD = ddname] 
[,OWNERID = name] 
[.PURGE = {YES }] 

{NO } ; 

where: 

TODD = (ddname,...) 

specifies the ddname of a job control statement defining a direct access device 
containing a volume to be formatted. Multiple ddnames specifying additional job 
control statements can be included. If multiple volumes are specified in a FORMAT 
statement and an abnormal completion of the FORMAT operation occurs, the 
operation is terminated on all volumes. 

VTOG = xxxxx 

specifies a one- to five-byte decimal relative track address representing a primary 
track on which the volume table of contents is to begin. The VTOG cannot occupy 
track 0, or track 1 if IPL text is written for 2303 and 2311 volumes. 

EXTENT = xxxxx 

specifies the decimal length of the VTOG in tracks. The VTOG cannot extend into 
the alternate track area or to a second volume. 

NEWVOLID = serial 

specifies a one- to six-character serial number. The serial number is assigned to all 
direct access volumes processed through the use of this control statement. If 
NEWVOLID is omitted, the direct access volumes retain their own serial numbers. 

IPLDD = ddname 

specifies the ddname of a DD statement defining the data set containing the IPL 
program. The IPL program can be included in the SYSIN (input stream) data set, or 
it can be defined as a sequential data set or a member of a partitioned data set. If 
IPL text is included in the input stream, an IPLTXT statement is used to separate 
the FORMAT statement from the program text statements. Maximum IPL record 
size is 3625 bytes. This parameter applies to 2301, 2303, 2305, 2311, 2314, 
2319, and 3330 volumes. 

Note: Gaution should be used to ensure that the DD statement being referred to is 
coded correctly. An incorrectly DD statement results in a loss of the time required 
to perform the FORMAT function. 

OWNERID = name 

specifies a one- to ten-character name or other identifying information to be 
placed in the volume label record. OWNERID is specified as an EBGDIG character 
string with the exclusion of the blank and the comma characters (these terminate 
the control card scan of a field or an entire card). 

PURGE = 

specifies whether the FORMAT operation is to be terminated when an unexpired 
data set is encountered. If PURGE is omitted and an unexpired data set is 
encountered, the FORMAT operation is terminated. These values can be coded: 

YES 

indicates that all unexpired data sets on the volume can be overwritten provided 
that the operator signals his concurrence when the first unexpired data set is 
encountered. 

NO 

specifies that the FORMAT operation is to be terminated when an unexpired data 
set is encountered. This is the default. 

If PURGE = YES is coded and an unexpired data set is encountered, the operator is 
prompted. The operator replies are: 

• U, which indicates that all unexpired data sets on this volume can be overwritten. 
(The FORMAT operation continues.) 

• T, which indicates that this volume contains unexpired data sets that must not be 
overwritten. (The FORMAT operation is terminated.) 
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LABEL Statement 



GETALT Statement 



DUMP Statement 



The PURGE parameter does not apply to password- protected data sets; that is, the 
operator must always respond with the proper password for each password-protected 
data set encountered. If he is unable to do so, the FORMAT operation is terminated. 

The LABEL statement is used to change the serial number of a direct access volume 
and, optionally, to update the owner field in record 3 of track 0. One LABEL statement 
must be included for each volume that is to have its label changed. 

The format of the LABEL statement is: 

[lat)el] LABEL TODD = {cuu } 

{ddname } 

.NEWVOLID = serial 

[.OWNERID = name] 



where: 

TODD = 

specifies the volume to be processed. These values can be coded: 

cuu 

specifies the channel and unit address of a direct access device containing a 
volume whose serial number is to be changed. This value is used only for 
labeling an off line volume. If the volume to be processed is a 2321 volume, 
TODD = cuu/b is specified, where cuu is the channel and unit address of the 
device and b is the bin number of the volume. If this volume is coded, no DD 
statement defining a mountable device is required. When this volume is coded, 
the specified device must be varied off line (by use of the VARY OFFLINE 
command) prior to the execution of the job step. 

ddname 

specifies the ddname of a job control statement defining a direct access device 
containing a volume whose serial number is to be changed. 

NEWVOLID = serial 

specifies a one- to six-character serial number. The serial number is assigned to 
the direct access volume processed through the use of this control statement. 

OWNERID = name 

specifies a one- to ten-character name or other identifying information. If 
OWNERID is omitted, the old owner information, if any, is retained. OWNERID is 
specified as an EBCDIC character string with the exclusion of the blank, the dash, 
and the comma characters (these terminate the control card scan of a field or an 
entire card). 

The GETALT statement is used to assign an alternate track for a specified data cell or 
disk track if the volume was previously initialized. 

The format of the GETALT statement is: 

[latjef] GETALT TODD = ddname 

.TRACK = cccchhhh 
where: 

TODD = ddname 

specifies the ddname of a job control statement defining a data cell or disk device 
containing a volume on which an alternate track is to be assigned. 

TRACK = cccchhhh 

specifies in hexadecimal the cylinder number, cccc, and head number, hhhh, of a 
track for which an alternate track is requested. (When referring to a 2321 volume, 
cccc is the subcell and strip address, and hhhh is the cylinder and head address. 
TRACK cannot specify track or the first track occupied by the VTOC. 

Note: Flags set by the GETALT statement for defective 3330 tracks cannot be reset by 
lEHDASDR. 

The DUMP statement dumps a single track, a group of consecutive tracks, or an entire 
direct access volume to one or more direct access volumes of the same device type, 
to one or more tape volumes, or to a system output device (printer assumed). 

A detailed description of the tape volume format is available in the IBM System/360 
Operating System: Utilities, Program Logic Manual, GY28-6614. 
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The format of the DUMP statement is: 

r l/abe/] DUMP FROiVIDD = dcfname ! 

I JODD = (cfdname,...) \ 

\ [,CPYVOLID= {YES} | 

I {NO}] I 

\ [.BEGIN = cccchhhh] \ 

I [,END = cccchhhh] 1 

I [.PURGE = {YES} 

L.,._„ _ .„._„ JMI..^,„ ..^^..1„_..._ „ „.. J 

where: 

FROMDD = ddname 

specifies the ddname of the DD statement defining the device containing the direct 
access volume from which a copy or copies are to be made. 

TODD = {ddname,...) 

specifies the ddname of the system output device (SYSPRINT) or specifies the 
ddnames of the DD statements defining the devices containing the direct access or 
tape volumes on which copies are to be made. If TODD = SYSPRINT is coded, the 
direct access volume described by FROMDD is dumped to the system output 
device. If a permanent data check or missing address marker is encountered while 
reading the direct access volume, the defective records are identified and printed. 
Output may exceed the expected data size due to a data check in the count field of 
the error record. When dumping from a 2305 or 3330 to SYSPRINT. the SPACE 
parameter must be used on the SYSPRINT DD card. Allocate sufficient space, for 
example, "5,(5)", to allow large capacity devices to dump to SYSPRINT. 

CPYVOLID = 

specified whether receiving direct access volumes are to be assigned the serial 
number of the dumped volume. If CPYVOLID is omitted, receiving volumes keep 
their own serial numbers. These values can be coded: 

YES 

specifies that all receiving direct access volumes are to be assigned the serial 
number of the dumped volume. 

NO 

specifies that receiving volumes are to keep their own serial numbers. This is the 
default. 

BEGIN = cccchhhh 

specifies in hexadecimal a cylinder number, cccc and head number, hhhh, that 
identify the first track to be dumped. (When referring to a 2321 volume, cccc is the 
subcell and strip address, and hhhh is the cylinder and head address.) If BEGIN is 
omitted, the dump operation begins with track 0. 

END = cccchhhh 

specifies in hexadecimal a cylinder number, cccc, and head number, hhhh, that 
identify the last track to be dumped. If only one track is to be dumped, both BEGIN 
and END specify that track address. (When referring to a 2321 volume, cccc is the 
subcell and strip address, and hhhh is the cylinder and head address.) If END is 
omitted, the last primary track of the volume is the last track to be copied. 
(Alternate tracks are not dumped unless they are assigned as alternates.) 

PURGE = 

specifies whether the dump operation is to be terminated when an unexpired data 
set is encountered. If PURGE is omitted, the dump operation is terminated when an 
unexpired data set is encountered. PURGE does not apply when dumping to a 
restore tape. These values can be coded: 

YES 

indicates that all unexpired data sets on a receiving direct access volume can be 
overwitten, provided that the operator signals his concurrence when the first 
unexpired data set is encountered. 

NO 

specifies that the dump operation is to be terminated when an unexpired data 
set is encountered. This is the default. 



lEHDASDR Program 199 



RESTORE Statement 



If PURGE = YES is coded and an unexpired data set is encountered, tlie operator is 
prompted. The operator replies are: 

• U, which indicates that all unexpired data sets on the receiving direct access 
volume can be overwritten. (The DUMP operation continues.) 

• T, which indicates that the receiving direct access volume contains unexpired data 
sets that must not be overwritten. (The DUMP operation is terminated.) 

The PURGE parameter does not apply to password-protected data sets; that is, the 
operator must always respond with the proper password for each password-protected 
data set encountered. If he is unable to do so, the dump operation is terminated. 

An extra input/output error (data check) message is generated at the console when 
the dump to SYSPRINT function encounters one of the following conditions: 

• Missing address marker. 

• Data check in count and key fields and/or data field. 

• Input/output error on a search command. 

• Missing address marker and no record found. 

The additional data check message printed at the console is generated by the dump 
function's error recovery procedure. However, the additional message is not reflected 
by a SYNADAF message in the SYSPRINT data set. If a missing address marker is 
encountered during a space count command, the function terminates with a return 
code of 8. 

Note: If multiple output volumes are specified in a DUMP statement and an abnormal 
completion of the DUMP operation occurs, the operation is terminated on all output 
volumes. 

Do not dump a volume and restore new data to that volume in the same job step. 
lEHDASDR does not flush the input stream if an operation is unsuccessful; that is, the 
program attempts to perform any remaining functions after encountering an error. 
Thus, if a dump operation is unsuccessful, data is lost if a subsequent restore 
operation places new data on the dumped volume. 

Partial dumps of direct access volumes should be used with extreme caution. Because 
only those tracks that are dumped are placed on the receiving volume, the partially 
dumped data may not be usable. When partially dumped data is subsequently 
restored, it is placed on the same tracks that it originally occupied. 

When using the DUMP statement, do not specify the same ddname in more than one 
TODD parameter in a single job step, except when the ddname is SYSPRINT. 

When space permits, more than one direct access volume can be dumped to a restore 
tape. However, lEHDASDR creates two files for each volume of data that is dumped. 
Therefore, the LABEL parameter sequence number in the DD statement defining the 
restore volume must be coded as 3, 5, 7, etc. for the second, third, fourth, etc. 
volume dumped to the restore tape. 

In the case of an IPL restore tape, the LABEL parameter sequence number must be 
coded as 2, 4, 6, etc. for the first, second, third, etc. volume dumped to the restore 
tape. 

The files are referred to in the same manner when restoring data to a direct access 
device. 

When processing an unlabeled tape before a dump operation, the lEHDASDR writes an 
end-of-file record (tapemark) and continues processing. 

When dumping to or restoring from a tape, specified as standard label or "BLP", a 
disposition of KEEP should be specified in the DD statement for the tape. Unlabeled 
tapes may have other disposition parameters. 

When restoring from a restore file on a tape, the same file sequence number and tape 
label format used in the dump operation must be used. 

Intermixing of restore files with system data sets is not recommended because of the 
unique format of the restore file. C 

The RESTORE statement is used to restore a direct access volume or volumes from a 
tape volume on which a dumped copy was previously placed. 

Note: When a standard labeled restore tape created by IBCDMPRS is restored by 

lEHDASDR, the DD card describing the tape for lEHDASDR can specify 

LABEL = (2,BLP). Bypass label processing must have been system generated by 
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specifying OPTIONS = BYLABEL on the SCHEDULR control card. If bypass label 
processing is not available, any standard labeled tape created by IBCDMPRS can be 
restored by lEHDASDR, by providing appropriate DCB parameters on the DD 
statement for the tape (RECFM = U.BLKSIZE = track length). 

The format of the RESTORE statement is: 

I [label] RESTORE TODD = (ddname,...) j 

.FROMDD = ddname \ 

[.CPYVOLID = {YES }] 1 

I (NO } i 
[.PURGE = {YES }] 

{NO } _^ ^___ _■ 

where':' "' " """ """"'~" '' 

TODD = (ddname,...) 

specifies the ddnames of the DD statements defining the devices containing the 
direct access volumes to be restored. If multiple output volumes are specified in a 
RESTORE statement and an abnormal completion of the restore operation occurs, 
the operation is terminated on all output volumes. 

FROMDD = ddname 

specifies the ddname of the DD statement defining the tape volume containing the 
data to be restored. If more than one tape volume is to be used as input, the DD 
statement for the tape must indicate multiple volumes. 

CPYVOLID 

specifies whether restored direct access volumes are to be assigned the serial 
number of the dumped direct access device. If CPYVOLID is omitted, receiving 
volumes keep their own serial numbers. These values can be coded: 

YES 

specifies that all restored direct access volumes are to be assigned the serial 
number of the dumped direct access volume. 

NO 

specifies that receiving volumes are to keep their own serial numbers. This is the 
default. 

PURGE = 

specifies whether the restore operation is to be terminated when an unexpired data 
set is encountered. If PURGE is omitted, the restore operation is terminated when 
an unexpired data set is encountered. 

YES 

specifies that all unexpired data sets on the receiving direct access volume can 
be overwritten provided that the operator signals his concurrence when the first 
unexpired data set is encountered. 

NO 

specifies that the restore operation is to be terminated if an unexpired data set 
I is encountered. This is the default. 

If PURGE = YES is coded and an unexpired data set is encountered, the operator is 
prompted. The operator replies are: 

• U, which indicates that all unexpired data sets on this volume can be overwritten. 
(The restore operation continues.) 

• T, which indicates that this volume contains unexpired data sets that must not be 
overwritten. (The restore operation is terminated.) 

The PURGE parameter does not apply to password-protected data sets; that is, the 
operator must always respond with the proper password for each password-protected 
data set encountered. If he is unable to do so, the restore operation is terminated. 

IPLTXT Statement The IPLTXT statement is used to mark the beginning of IPL program text statements. 

The IPL text must follow the first statement referring to it. 

IPL text need be included only once in the input stream; that is, lEHDASDR refers to 
the first copy of IPL text encountered when performing multiple functions in a single 
job step. 

The format for the IPLTXT statement is: 



lEHDASDR Program 201 



lEHDASDR Examples 



The following examples illustrate some of the uses of lEHDASDR. Table 37 can be 
used as a quick reference guide to lEHDASDR examples. The numbers in the 
"Example" column point to examples that follow. 
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Table 37. lEHDASDR Example Directory 

Operation Device Comments 

INITIALIZE 2314 Disk Volume is to be initialized for the first time; 

therefore, recording serface is analyzed. IPL 
text is included in the input stream. 

INITIALIZE 231 1 Disks Three previously initialized volumes are to 

be initialized; their volume serial numbers are 
to be changed. Surface analysis is to be 
performed at the same time. 

Get alternate tracks for a previously initialized 
volume and change its volume serial number. 

Dump a copy of one volume to three other 
volumes. 

Dump a group of tracks to the system output 
device, which is assumed to be a printer. 

Dump a disk volume to magnetic tape. Only 
one tape volume is required. 

A 2311 disk volume, previously dumped to 
tape, is to be restored to direct access. 

Dump operations are to be performed 
concurrently to minimize input/output time. 
Restore operations are to be performed 
concurrently to minimize input/output time. 

A 2314 volume, previously dumped to two tape 
volumes, is to be restored to disk. 

Format a disk by writing an RO on each 
track. IPL text is included in the 
input stream. The volume serial is 
changed. 

FORMAT 3330 Disks Format two disks. 

Quick-DASDI 3330 Disk Use the ANALYZE function to build the 

VTOC and change the volume serial number. 



Example 



GETALT 
and LABEL 


2321 Disk 


DUMP 


2314 Disks 


DUMP 


2311 Disk, 
system output 
device 


DUMP 


2314 Disk, 
9-track tape 


RESTORE 


2311 Disks, 
7 -track tape 


DUMP and 
RESTORE 


2314 Disks, 
9-track tape 


RESTORE 


9-track tape, 
2314 Disk 


FORMAT 


3330 Disk 



10 

11 

12 



In this example, a blank 2314 volume is to be analyzed and formatted for the first 
time. Because this example deals with a blank volume, two considerations must be 
made: 

1. The TODD parameter in the ANALYZE statement must specify a channel and unit 
address, rather than a ddname. 

2. The selected device (in this example, unit 190) must be varied offline by the 
operator; that is, before the job is executed, the operator must use the VARY 
OFFLINE command. 



The example follows: 

//DASDR1 

// 

//SYSPRINT 
//SYSIN 
ANALYZE 



JOB 

EXEC PGM=IEHDASDR 
DD SYSOUT=A 
DD * 
T0DD=1 90 , VTOC=00004 , EXTEND=000 1 , 
NEWVOLID=23 1400, OWNERID=SMITH , 
IPLDD=SYSIN , FLAGTEST=NO 



nc 
lie 



IPLTXT 
TXT 

(IPL text) 

TXT 
END 
/* 

The control statements are discussed below: 

• SYSIN DD defines the control data set, which follows in the input stream. 
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• ANALYZE defines a mountable device on which a blank 2314 volume Is to be 
mounted. This statement defines the starting location and extent of a volume table 
of contents, specifies a serial number and owner identification, indicates that no 
flag testing is to be performed, and indicates that IPL text is Included In the Input 
stream. 

• IPLTXT signals the start of IPL text. 

• END signals the end of IPL text. 

In this example, three previously initialized 2311 volumes are to be initialized and 
assigned new serial numbers. 

The example follows: 

//DASDR2 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//VOLl DD UNIT=( 231 1 , ,DEFER),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231 100 ) ) 

//V0L2 DD UNIT=( 231 1 , ,DEFER),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 2311 01 ) ) 

//V0L3 DD UNIT=( 2311 , ,DEFER),DISP=OLD, 

// VOLUME=( PRIVATE , , SER=( 231102)) 

//SYSIN DD * 

ANALYZE T0DD=V0L1 , VTOC=00003 , EXTENT=000 1 , 

OWNERID=SMITH , NEWVOLID=DISK0 1 , FLAGTEST=NO 

ANALYZE T0DD=V0L2 , VTOC=00006 , EXTENT=000 1 , 

OWNERID=SMITH , NEWVOLID=DISK02 , FLAGTEST=NO 

ANALYZE T0DD=V0L3 , VTOC=00004 , EXTENT=000 1 , 

OWNERID=SMITH , NEWVOLID=DISK03 , FLAGTEST=NO 



lie 
lie 
lie 



/* 

The control statements are discussed below: 

• VOLl, V0L2, and V0L3 DD define three 2311 devices on which the volumes to be 
initialized are mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The ANALYZE statements indicate the ddnames of DD statements defining devices 
on which the three 2311 volumes (231100, 231101, and 231102) are to be 
mounted. The ANALYZE statements also define starting locations and extents of 
the three volume tables of contents, specify new owner names and serial numbers 
(DISKOl, DISK02, and DISK03), and indicate that no flag testing is to be performed 
on these volumes. 

In this example, alternate tracks are to be assigned for three suspected defective 
tracks on a 2321 volume. 

The example follows: 

//DASDR3 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//VOLUMEI DD UNIT=( 2321 , ,DEFER),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 232100) ) 

//SYSIN DD * 

GETALT T0DD=V0LUME1 ,TRACK=050703 1 

GETALT TODD= VOLUME 1 , TRACK= 0A06020F 

GETALT T0DD=V0LUME1 , TRACK=0A0703 1 1 
LABEL T0DD=V0LUME1 ,NEWVOLID=DISK00 ,OWNERID=SMITH 
/* 

The control statements are discussed below: 

• VOLUMEI DD defines a device that is to contain the 2321 volume (232100). 

• SYSIN DD defines the control data set, which follows in the input stream. 

• The GETALT statements specify the ddname of the DD statement defining the 
device on which the 2321 volume is mounted. The GETALT statements specify the 
relative track addresses of the tracks for which alternates are to be assigned. 

• LABEL specifies the ddname of the DD statement defining the device on which the 
2321 volume is mounted. The LABEL statement changes the serial number of the 
2321 volume from 232100 to DISKOO. 
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In this example, a copy of an entire volume (231400) is to be dumped onto three 
volumes (231401, 231402, and 231403). 

The example follows: 

//DASDR4 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DUMPFROM DD UNIT=( 23 14 , ,DEFER ) ,DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 231400 ) ) 
//DUMPT01 DD UNIT=( 2314, , DEFER ),DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 231401 ) ) 
//DU]yiPT02 DD UNIT=( 2314, , DEFER ),DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 231402 ) ) 
//DUMPT03 DD UNIT={ 23 1 4 , ,DEFER ) ,DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 231403 ) ) 
//SYSIN DD * 
DUMP FROMDD=DUMPFROM , TODD= ( DUMPTO 1 , DUMPT02 , DUMPT03 ) , »C 
PURGE=YES 
/* 

The control statements are discussed below: 

• DUMPFROM DD defines a mountable device that is to contain a source volume. 

• DUMPTOl, DUMPT02, and DUMPT03 DD define mountable devices that are to 
contain the three receiving volumes. 

• DUMP specifies the dump operation and identifies the DD statements defining the 
applicable devices. All receiving volumes are to retain their own serial numbers. 

In this example, a copy of tracks through 60 is to be dumped from a disk volume 
(231100) to a system output device. 

The example follows: 

//DASDR5 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DEV DD UNIT=( 2311,, DEFER ) , DISP=OLD , 

// VOLUME=( PRIVATE, , SER=( 231 1 00 ) ) 

//SYSIN DD * 

DUMP FROMDD=DEV,TODD=SYSPRINT,BEGIN=00000000,END=00050009 
/* 

The control statements are discussed below: 

• DEV DD defines a mountable device that is to contain the source volume. 

• DUMP specifies the dump operation, identifies the DD statements defining the 
source and receiving devices, and identifies the tracks that are to printed. 

In this example, a 2314 volume (231400) is to be dumped to a 9-track, 800 bits per 
inch, tape volume (240000). 

The example follows: 

//DASDR6 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, , SER=( 23 1400 ) ) 

//RECEIVE DD UNIT=( 2400, , DEFER ) ,DISP=NEW,DSNAME=TAPE1 , 

// VOLUME=( PRIVATE, , SER=( 240000 ) ) 

//SYSIN DD * 

DUMP FROMDD=SOURCE,TODD=RECEIVE 
/* 

Note: This example assumes that only one tape volume is required. If more than one is 
required, code the volume serial numbers of the additional volumes in the VOLUME 
parameter of the DD statement that defines the magnetic tape device. For unlabeled 
tapes, include a volume count in the DD statement. 

The control statements are discussed below: 

• SOURCE DD defines a mountable device that is to contain the source volume. 

• RECEIVE DD defines a 9-track tape drive that is to contain the receiving tape 
volume. 

• DUMP specifies the dump operation and identifies the DD statements defining the 
source and receiving devices. 
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In this example, three disk volumes (231100, 231101, and 231102) are to be 
restored from a 7-track, 556 bits per inch, standard labeled, tape volume. 

The example follows: 

//DASDR7 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//TAPE DD UNIT=( 2400-2, , DEFER ),DISP=OLD,DCB=(TRTCH=C, 

// ,DEN=1 ),DSNAME=TAPE1 ,VOLUME=( PRIVATE, ,SER=( 240000 ) ) 

//DIRACC1 DD UNIT=( 2311 , ,DEFER),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=(231 100 ) ) 

//DIRACC2 DD UNIT=( 23 1 1 ,, DEFER ), DISP=OLD, 

// VOLUME=( PRIVATE , , SER=( 231101)) 

//DIRACC3 DD UNIT=( 23 1 1 ,, DEFER ) ,DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=(231 102 ) ) 

//SYSIN DD * 

RESTORE TODD={ DIRACC1 ,DIRACC2 ,DIRACC3 ) , FROMDD=TAPE 
/* 

The control statements are discussed below: 

• TAPE DD defines a 7-track tape drive that is to contain the source tape volume. 

• DIRACCl, DIRACC2, and DIRACC3 DD define mountable devices that are to 
contain the three receiving volumes. 

• RESTORE specifies the restore operation and identifies the DD statements defining 
the source and receiving devices. The receiving volumes retain their own serial 
numbers. 

In this example, two direct access volumes are to be dumped concurrently to two 
receiving volumes in one operation; two direct access volumes are to be restored 
concurrently from two 9-track, 800 bits per inch, standard labeled, tape volumes in 
another operation. 

The example follows: 

//DASDR8 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//SOURCE 1 DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, , SER=( 231400 ) ) 

//SOURCE2 DD UNIT={ 231 4 , , DEFER ) , DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231401 )) 

//T01 DD UNIT=2314,VOLUME=SER=231402,DISP=OLD 

//T02 DD UNIT=2314,VOLUME=SER=231403,DISP=OLD 

//S0URCE3 DD UNIT=( 2400 ,, DEFER ) ,DISP=OLD, LABEL=( ,NL) , 

// VOLUME=( PRIVATE , , SER=( 240000 ) ) 

//S0URCE4 DD UNIT=( 2400 ,, DEFER ), DISP=OLD, LABEL=( , NL) , 

// VOLUME=( PRIVATE, ,SER=( 240001 ) ) 



//T03 
//T04 
//SYSIN 



DD UNIT=AFF=T01 , VOLUME=SER=23 1 404 , DISP=OLD 

DD UNIT=AFF=T02 , VOLUME=SER=23 1 405 , DISP=OLD 

DD * 

DUMP FROMDD=SOURCE 1 , TODD=TO 1 

DUMP FR0MDD=S0URCE2 , T0DD=T02 

RESTORE TODD=T03,FROMDD=SOURCE3 

RESTORE T0DD=T04 , FR0MDD=S0URCE4 

/* 

The control statements are discussed below: 

• SOURCEl and S0URCE2 DD define devices on which the source volumes for the 
dump operation are to be mounted. 

• TOl and T02 DD define devices on which the receiving volumes for the dump 
operation are to be mounted. 

• SOURCES and S0URCE4 DD define devices on which the source tape volumes for 
the restore operation are to be mounted. 

• T03 and T04 DD define devices on which the receiving direct access volumes for 
the restore operation are to be mounted. The receiving volumes for the restore 
operation are to be mounted on the same devices as the receiving volumes for the 
dump operation were mounted. 
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In this example, a 2314 volume previously dumped to tape is to be restored. Because 
a completely filled 2314 volume requires more space than is available on a single reel 
of 9-track, 800 bits per inch tape, two tape volumes were used in the dump operation. 

The example follows: 

//DASDR9 JOB 00#990, SMITH 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//TAPE DD UNIT=2400,VOL=( ,,,2, SER=( 240000, 240001 ) ), 

// DISP=OLD 

//DISK DD UNIT=2314,VOL=SER=231400,DISP=OLD 

//SYS IN DD * 

RESTORE FROMDD=TAPE , TODD=DISK 
/* 

The control statements are discussed below: 

• TAPE DD defines the 9-track tape volumes that contain the data to be restored to 
disk. 

• DISK DD defines the 2314 volume to which data is to be restored. 

• RESTORE specifies that data is to be restored from the tape volumes defined in the 
TAPE DD statement to the 2314 volume defined in the DISK DD statement. 

• For unlabeled tapes, use the external volume identification and the LABEL = (,NL) 
parameter on the associated tape DD statement. 

In this example, a 3330 volume is formatted and assigned a new serial number. 

The example follows: 

//DASDR10 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DISK DD UNIT=3330,DISP=OLD,VOL=( PRIVATE, ,SER=( 333000 ) ) 

//SYSIN DD * 

FORMAT TODD=DISK,VTOC=00006,EXTENT=00005, l^C 

NEWVOLID=33300 1 , PURGE=YES , IPLDD=SYSIN 

IPLTXT 

TXT 

( IPL text ) 

TXT 

END 
/* 

The control statements are discussed below: 

• DISK DD defines the 3330 device on which the volume (333000) is mounted. 

• SYSIN DD defines the control data set which follows in the input stream. 

• FORMAT defines a starting location and extent of a volume table of contents, 
specifies a new serial number, and indicates that the IPL text is included in the 
input stream. Record of each track is rewritten. 

• IPLTXT signals the start of IPL text. 

• END signals the end of IPL text. 

In this example, two 3330 volumes are formatted. 
The example follows: 

//DASDR1 1 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DISK01 DD UNIT=3330,DISP=OLD,VOL=( PRIVATE, ,SER=( 333001 ) ) 

//DISK02 DD UNIT=3330,DISP=OLD,VOL=( PRIVATE, ,SER=( 333002) ) 

//SYSIN DD * 

FORMAT TODD=(DISK01 ,DISK02 ) , VTOC=0001 ,EXTENT=0001 
/* 

The control statements are discussed below: 

• DISKOl and DISK02 DD statements define the 3330 devices on which the volumes 
(333001, 333002) are mounted. 

• FORMAT defines a starting location and extent of a volume table of contents. The 
Record of each track is rewritten. 
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In this example, a 3330 volume is initialized with a VTOC and volume serial number, or 
"quick-DASDI". 

The example follows: 

//DASDR12 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DISK DD UNIT=3330,DISP=OLD,VOL=( PRIVATE, ,SER=( 333000) ) 

//SYSIN DD * 

ANALYZE TODD=DISK, VTOC=00005 , EXTENT=0001 , NEWVOLID=333333 
/* 

The control statements are discussed below: 

• DISK DD defines the 3330 device on which the volume (333000) is mounted. 

• ANALYZE defines the starting location and extent of a volume table of contents. For 
3330 devices, PASSES = is the default so that only a "quick-DASDI" is 
performed. 
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lEHINITT is a system utility used to place IBM volume label sets written in EBCDIC, in 
BCD, or in ASCII (American Standard Code for Information Interchange) on magnetic 
tapes mounted on one or more tape drives. (See "Introduction" for general system 
utility information.) Each volume label set created by the program contains: 

• A standard volume label with user specified serial number and owner identification. 

• An 80-byte dummy header label. For IBM standard labels, this record consists of 
HDRl followed by zeros. For ANS labels, this record consists of HDRl followed by 
zeros in the remaining positions, with the exception of position 54, which contains 
an ASCII space. 

• A tapemark. 

Note: When a labeled tape is subsequently used as a receiving volume: (1) the tape 
mark created by lEHINITT is overwritten, (2) the dummy HDRl record created by 
lEHINITT is filled in with operating system data and device dependent information, (3) 
a HDR2 record, containing data set characteristics, is created, (4) user header labels 
are written if exits to user label routines are provided, (5) a tapemark is written, and 
(6) data is placed on the receiving volume. 

Figure 44 shows an IBM standard label group after a volume is used to receive data. 
Refer to OS Data Management Services Guide, GC26-3746, for a discussion of volume 
labels. 



Placing a Standard 
Label Set on 
Magnetic Tape 



Initial volume label 



HDRl 



HDR2 



User header labels 
(optional up to 8) 



Tape mark 



Data 



Figure 44. IBM Standard Label Group After Volume Receives Data 

lEHINITT can be used to write BCD labels on 7-track tape volumes and EBCDIC or 
ASCII labels on 9-track tape volumes. Any number of 7-track and/or 9-track tape 
volumes can be labeled in a single execution of lEHINITT. 

Tape volumes are labeled in sequential order by specifying a serial number to be 
written on the first tape volume. The serial number is incremented by 1 for each 
successive tape volume. If only one tape volume is to be labeled, the specified serial 
number can be either numeric or alphameric. If more than one volume is to be labeled, 
the serial numbers must be specified as six numeric characters. 

The user can provide additional information, such as owner name, rewind or unload 
specifications, and whether the label is to be written in ASCII. 

The user must supply all tapes to be labeled, and must include with each job request 
explicit instructions to the operator about where each tape is to be mounted. 

If any errors are encountered while attempting to label a tape, the tape is left 
unlabeled. lEHINITT attempts to label any tapes remaining to be processed. 

For information on creating routines to write standard or nonstandard labels, refer to 
OS Data Management for System Programmers, GC28-6550. 

lEHINITT writes 7-track tape labels in even parity (translator on, converter off). 

Previously labeled tapes can be overwritten with new labels regardless of expiration 
date and security protection. 
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lEHINITT uses as input a control data set that contains the utility control statements. 

lEHINITT produces an output data set that contains: (1) utility program identification, 
(2) initial volume label information for each successfully labeled tape volume, (3) 
contents of utility control statements, and (4) any error messages. 

lEHINITT produces a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. A message data set was created. 

• 04, which indicates successful completion. No message data set was defined by the 
user. 

• 08, which indicates that the program completed its operation, but error conditions 
were encountered during processing. A message data set was created. 

• 12, which indicates that the program completed its operation, but error conditions 
were encountered during processing. No message data set was defined by the user. 

• 16, which indicates that the program terminated operation because of error 
conditions encountered while attempting to read the control data set. A message 
data set was created if defined by the user. 

lEHINITT is controlled by job control statements and utility control statements. The job 
control statements are used to execute or invoke lEHINITT and to define data sets 
used and produced by lEHINITT. Utility control statements are used to specify 
applicable label information. 

Table 38 shows the job control statements necessary for using lEHINITT, 

Table 38. lEHINITT Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = lEHINITT) or, if the job control statements 

reside in a procedure library, the procedure name. The EXEC statement can 
include additional PARM information; see "PARM Information on the EXEC 
Statement." 

SYSPRINT DD Defines a sequential message data set. 

anyname DD Defines a tape drive to be used in a labeling operation; more than one tape drive 
can be identified. 

SYSIN DD Defines the control data set. The control data set normally resides in the input 

stream; however, it can be defined as a member of a partitioned data set or as a 
sequential data set outside the input stream. 

The minimum region size that can be specified for lEHINITT is 14K. 

The "anyname" DD statement is entered: 

//anyname DD DCB = DEN = x,UNIT = (xxxx,n,DEFER) 

The DEN parameter specifies the density at which the labels are written. The UNIT 
parameter specifies the device type, number of drives to be used for the labeling 
operation, and deferred mounting. The name "anyname" must be identical to a name 
specified in a utility control statement to relate the specified drive(s) to the 
appropriate utility control statement. 

• The SYSPRINT data set must have a logical record length of 121 bytes. It must 
consist of fixed length records with an ASA control character in the first byte of 
each record. Any blocking factor can be specified. 

• The SYSIN data set must have a block size that is a multiple of 80. Any blocking 
factor can be specified. 

• ANS labels can not be put on 7-track tape volumes. 

The EXEC statement can include PARM information that specifies the number of 
lines to be printed between headings in the message data set, as follows: 

PARM = LINECNT = nn 

If PARM is omitted, 60 lines are printed between headings. 

If lEHINITT is invoked, the line count option can be passed in a parameter list that is 
referred to by the "optionaddr" subparameter of the LINK or ATTACH macro 
instruction. In addition, a page count can be passed in a six-byte parameter list that is 
referred to by the "hdingaddr" subparameter of the LINK or ATTACH macro 
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instruction. For a discussion of linl<age conventions, refer to "Appendix B: Invoicing 
Utility Programs from a Problem Program." 

lEHINITT uses a utility control statement to provide control information for a labeling 
operation. 

The INITT statement provides control information for the lEHINITT program. 

Any number of INITT utility control statements can be included for a given execution 
of the program. An identically named DD statement must exist for a utility control 
statement in the job step. 

The format of the INITT statement is: 

name INITT SER == xxxxxx ; 

i [.OWNER = 'cccccccccc[cccc]'] \ 

[.NUMBTAPE = n] 
,DISP= {REWIND } 
{ UNLOAD ) 
; [.LABTYPE = AL] _ . ^ ^ j 

where: 

name 

specifies a name that is identical to a ddname in the name field of a DD statement 
defining a tape drive or drives. This name must begin in column 1. 

SER = xxxxxx 

specifies the volume serial number of the first or only tape to be labeled. The serial 
number cannot contain blanks, commas, apostrophes, equal signs, or special 
characters. A specified serial number is incremented by one for each additional 
tape to be labeled. (Serial number 999999 is incremented to 000000.) When 
processing multiple tapes, the volume serial number must be all numeric. 

OWNER = 'cccccccccc[ccccy 

specifies the owner's name or similar identification. The information is specified as 
character constants, and can be up to 10 bytes in length for EBCDIC and BCD 
volume labels, or up to 14 bytes in length for ANS volume labels. The delimiting 
apostrophes can be omitted if no blanks, commas, apostrophes, equal signs, or 
other special characters (except periods or hyphens) are included. If an apostrophe 
is included, it must be written as two consecutive apostrophes. 

NUMBTAPE = n 

specifies the number of tapes to be labeled according to the specifications made in 
this control statement. The value n represents a number from 1 to 255. If 
NUMBTAPE is omitted, one tape volume is labeled. 

DISP = 

specifies whether a tape is to be rewound or unloaded. These values can be coded: 

REWIND 

specifies that a tape is to be rewound (but not unloaded) after the label has 
been written. If DISP = REWIND is not specified, the tape volume is rewound and 
unloaded. 

UNLOAD 

specifies that a tape is to be unloaded after the label has been written. This is 
the default. 

LABTYPE = AL 

specifies that an ANS volume label is to be created. If LABTYPE is not specified, the 
tape is written in EBCDIC for 9-track tape volumes and in BCD for 7-track tape 
volumes. 

Figure 45 shows a printout of a message data set including the INITT statement and 
initial volume label information. In this example, one INITT statement was used to 
place serial numbers 001122 and 001123 on two tape volumes. VOLlOOl 12200 and 
VOL10011230 are interpreted, as follows: 

• VOLl indicates that an initial volume label was successfully written to a tape 
volume. 

• 001122 and 001123 are the serial numbers that were written onto the volumes. 

• is the Volume Security field. 

No errors occurred during processing. 
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SYSTEM SUPPORT UTILITIES 
ALL INITT 



lEHINITT 



SER=00 1122, NUMBTAPE=2 , OWNER= ' P . T . BROWN ' , 
DISP=REWIND 



»C 



V0L1 001 1220 
VOL10011230 



BROWN 
BROWN 



Figure 45. Printout of INITT Statement Specifications and Initial Volume Label 
Information 

The following examples illustrate some of the uses of lEHINITT. Table 39 can be used 
as a quick reference guide to lEHINITT examples. The numbers in the "Example" 
column point to examples that follow. 
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lEHINITT Example 2 



lEHINITT Example 3 



Table 39. lEHINITT Example Directory 

Operation Comments Example 

LABEL Three 9-track tapes are to be labeled. 1 

LABEL A 9-track tape Is to be labeled. 2 

LABEL Two groups of 9-track tape volumes are to be labeled. 3 

LABEL 9-track tape volumes are to be labeled. Sequence 

numbers are to be incremented by 10. 4 

LABEL Three 9-track tape volumes are to be labeled. An 

alphameric label is to be placed on a 2400 volume; 
numeric labels are placed on the 2400-4 volumes. 5 

In this example, serial numbers 001234, 001235, and 001236 are to be placed on 
three tape volumes; the labels are to be written in EBCDIC at 800 bits per inch. Each 
volume to be labeled is mounted, when it is required, on a single 9-track tape drive. 

The example follows: 

//LABEL 1 JOB 09#990, BROWN, MSGLEVEL=( 1,1) 

// EXEC PGM=IEHINITT 

//SYSPRINT DD SYSOUT=A 

//LABEL DD DCB=DEN=2 , UNIT=( 2400 , 1 , DEFER ) 

//SYSIN DD * 

LABEL INITT SER=00 1 234 ,NUMBTAPE=3 

/* 

In this example, serial number 001001 is to be placed to one ASCII tape volume; the 
label is to be written at 800 bits per inch. The volume to be labeled is mounted, when 
it is required, on a 9-track tape drive. 

The example follows: 



JOB 09#990 , BROWN , MSGLEVEL=( 1,1) 
EXEC PGM=IEHINITT 

SYSOUT=A 

DCB=DEN=2,UNIT=( 2400, 1 , DEFER) 

* 

SER=00 1 001, OWNER= ' SAM A . BROWN ' , LABTYPE=AL 



//LABEL2 

// 

//SYSPRINT DD 
//ASCI I LAB DD 
//SYSIN DD 
ASCIILAB INITT 
/* 

In this example, two groups of serial numbers (001234, 001235, 001236, and 
001334, 001335, 001336) are placed on six tape volumes. The labels are to be 
written in EBCDIC at 800 bits per inch. Each volume to be labeled is mounted, when it 
is required, on a single 9-track tape drive. 

The example follows: 

//LABEL3 JOB 09#990 , BROWN ,MSGLEVEL=( 1 , 1 ) 

// EXEC PGM=IEHINITT 

//SYSPRINT DD SYSOUT=A 

//LABEL DD DCB=DEN=2 , UNIT=( 2400,1, DEFER ) 

//SYSIN DD * 

LABEL INITT SER=00 1 234 ,NUMBTAPE=3 

LABEL INITT SER=00 1 334 ,NUMBTAPE=3 

/* 
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lEHINITT Example 4 



lEHINITT Example 5 



In this example, serial numbers 001234, 001244, 001254, 001264, 001274, etc., are 
to placed on eight tape volumes. The labels are to be written in EBCDIC at 800 bits 
per inch. Each volume to be labeled is mounted, when it is required, on one of four 
9-track tape drives. 

The example follows: 



//LABEL4 JOB 


09#990,BROWN,MSGLEVEL=( 1,1) 


// 


EXEC 


PGM=IEHINITT 


//SYSPRINT DD 


SYSOUT=A 


//LABEL 


DD 


DCB=DEN=2 , UNIT=( 2400 , 4 , DEFER 


//SYSIN 


DD 


* 


LABEL 


INITT 


SER=001234 


LABEL 


INITT 


SER=001244 


LABEL 


INITT 


SER=001254 


LABEL 


INITT 


SER=001264 


LABEL 


INITT 


SER=001274 


LABEL 


INITT 


SER=001284 


LABEL 


INITT 


SER=001294 


LABEL 


INITT 


SER=001304 


/* 







In this example, serial number TAPEl, is to be placed on a 2400 tape drive and serial 
numbers 001234 and 001235 are to be placed on two 2400-4 tape drives. The labels 
are to be written in EBCDIC at 800 and 1600 bits per inch. 

The example follows: 

//LABELS JOB 09#990 , BROWN, MSGLEVEL=( 1 , 1 ) 

// EXEC PGM=IEHINITT 

//SYSPRINT DD SYSOUT=A 

//LABEL1 DD DCB=DEN=2 , UNIT=( 2400 , 1 , DEFER ) 

//LABEL2 DD DCB=DEN=3 , UNIT=( 2400-4 , 1 , DEFER ) 

//SYSIN DD * 

LABEL 1 INITT SER=TAPE1 

LABEL2 INITT SER=001 234,NUMBTAPE=2 

/* 

Note: If 2400 tape drives are not available for allocation and the system configuration 
includes 3400 tape drives, a 3400 tape drive may be allocated by default. 
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lEHIOSUP Program 



Input and Output 



Control 

Job Control Statements 



Restrictions 



lEHIOSUP Examples 



lEHIOSUP is a system utility used to update TTR entries in the transfer control tables 
of the supervisor call library (SVC library). (See "Introduction" for general system 
utility information.) Because of the way SVC routines are loaded, it is necessary to 
update TTR entries after changing or replacing a module. lEHIOSUP automatically 
updates the TTR entries. lEHIOSUP must be used after: 

• The SVC library is moved. 

• The OPEN, CLOSE, TCLOSE, EOV, FEOV, SCRATCH, ALLOCATE, lEHATLAS, 
SETPRT, STOW, or any Machine Check Handler (MCH) recovery management 
module is changed or replaced in the SVC library. 

lEHIOSUP uses as input an object data set (SYSl.SVCLIB) that contains the transfer 
control tables that are to be updated. 

lEHIOSUP produces as output a message data set that contains any error messages 
generated during the execution of the program. 

lEHIOSUP produces a return code to indicate the results of program execution. The 
return codes and their interpretations are: 

• 00, which indicates successful completion. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

lEHIOSUP is executed or invoked with job control statements. Utility control 
statements are not used. 

Table 40 shows the job control statements necessary for using lEHIOSUP. 

Table 40. lEHIOSUP Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGIVI = lEHIOSUP) or, if the job control 

statements reside in a procedure library, the procedure name. 

SYSPRINT DD Defines a sequential message data set. 

SYSUTl DD Defines the object data set (SYSl.SVCLIB). The DSNAME, DISP, UNIT, and 

VOLUME parameters should be included. 

The minimum region size that can be specified for lEHIOSUP is lOK. 

If the SYSl.SVCLIB data set is cataloged, the UNIT and VOLUME parameters are not 
required on the SYSUTl DD statement. 

• PARM = TSO must be coded on the EXEC statement if the data set to be updated is 
from a TSO system. 

• The block size for the SYSPRINT data set must be a multiple of 121. Any blocking 
factor can be specified. 

The following examples illustrate some of the uses of lEHIOSUP. Table 41 can be used 
as a quick reference guide to lEHIOSUP examples. The numbers in the "Example" 
column point to examples that follow. 



Table 41. lEHIOSUP Example Directory 

Data Set 

Operation Organization Device Comments Example 

UPDATE Partitioned, 2314 Disk, SVC library is to be updated. 

Sequential system output SYSl.SVCLIB is not cataloged. 

device System output device is a printer. 1 

UPDATE Partitioned, 3330 Disk, SVC library is to be updated. 

Sequential system output SYSl.SVCLIB is cataloged. System 

device output device is a printer. 2 

UPDATE Partitioned, 2314 Disk, SVC library (TTRs) is to be updated 

Sequential system output on a TSO pack. SYSl.SVCLIB is 

device cataloged. System was generated 

for TSO. 3 
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lEHIOSUP Example 1 



lEHIOSUP Example 2 



lEHIOSUP Example 3 



In this example, the TTR entries in the SVC library are to be updated. 
The example follows: 

//TTRUPDTE JOB 

// EXEC PGM=IEHIOSUP 

//SYSUT1 DD DSNAME=SYS1 .SVCLIB,DISP=OLD,UNIT=2314, 

// V0LUME=SER=1 11111 

//SYSPRINT DD SYSOUT=A 

// 

The control statements are discussed below: 

• SYSUTl DD defines the object data set (the SYSl.SVCLIB data set). 

• SYSPRINT DD defines the message data set. 

In this example, the TTR entries in the SVC library are to be updated. 

The example follows: 

//SVCUPDTE JOB 

// EXEC PGM=IEHIOSUP 

//SYSUTl DD DSNAME=SYS1 .SVCLIB,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

// 

The control statements are discussed below: 

• SYSUTl DD defines the object data set (the SYSl.SVCLIB data set). Because the 
data set is cataloged, UNIT and VOLUME parameters are not required. 

• SYSPRINT DD defines the message data set. 

In this example, the TTR entries in a TSO SVC library are to be updated. 

The example follows: 

//TSOSVCUP JOB 

// EXEC PGM=IEHIOSUP, PARM=TSO 

//SYSUTl DD DSNAME=SYS1 .SVCLIB,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

// 

The control statements are discussed below: 

• SYSUTl DD defines the object data set (the SYSl.SVCLIB data set). Because the 
data set is cataloged, UNIT and VOLUME parameters are not required. 

• SYSPRINT DD defines the message data set. 
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lEHLIST Program 



Listing Catalog Entries 



lEHLIST is a system utility used to list entries in a catalog, entries in the directory of 
one or more partitioned data sets, or entries in a volume table of contents. (See 
"Introduction" for general system utility information.) Any number of listings can be 
requested in a single job. 

lEHLIST lists all catalog entries that are part of the structure of a fully-qualified data 
set name. Figure 46 shows an index structure for which lEHLIST lists fully-qualified 
names A.B.D.W, A.B.D.X, A.B.E.Y, and A.B.E.Z. Because A.C.F does not represent a 
cataloged data set (that is, the lowest level of qualification has been deleted), it is not 
a fully-qualified name, and it is not listed. 



Listing a Partitioned 
Data Set Directory 



Edited Format 






? 1 

W X Y Z 

Figure 46. Index Structure — Listed by lEHLIST 



lEHLIST can list up to ten partitioned data set directories in a single application of 
the program. A partitioned directory is composed of variable length records blocked 
into 256-byte blocks. Each directory block can contain one or more entries which 
reflect member (and/or alias) names and other attributes of the partitioned members 
in edited and unedited format. 

Figure 47 shows a directory block as it exists in storage. 
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47. Sample Directory Block 

















lEHLIST optionally provides the following information, which is obtained from the 
applicable partitioned data set directory, when an edited format is requested: 

• Member name 

• Entry point 

• Attributes 

• Relative address of start of member 

• Relative address of start of text 

• Contiguous main storage requirements 

• Length of first block of text 

• Origin of first block of text 

• System status indicators 

• Other information 

Before printing the directory entries on the first page, an index is printed explaining 
the asterisk (*) following a member name, the attributes (field 3) and other iriformation 
(field 10). Under the ATTRIBUTE INDEX, the meaning of each attribute bit is 
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explained; under the OTHER INFORMATION INDEX, scatter and overlay format data is 
described, positionally, as it appears in the listing. 

Each directory entry occupies one printed line, except when the member name is an 
alias and the main member name and associated entry point appear in the user data 
field. When this occurs, two lines are used and every alias is followed by an asterisk. 

Note: The FORMAT option applies only to a partitioned data set whose members have 
been created by the Linkage Editor (that is, the directory entries are at least 34 bytes 
long). If a directory entry is less than 34 bytes, a message is issued and the entry is 
printed in unedited format; if the entry is longer than 34 bytes, it is assumed that it is 
created by the Linkage Editor. 

Figure 48 shows an edited entry for a partitioned member (lEANUCOl). The entry is 
shown as it is listed by the lEHLIST program. 
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"-1 


■ • 


MEMBER 


ENTRY 


ATTR 


REL 


ADDR-HEX 


CONTIG 


LEN 1st ORG 1st SSI 


OTHER 


• 1 


I 


NAME 


PT-HEX 


HEX 


BEGIN 


IstTXT 


STOR-DEC 


TXT-DEC TXT-HEX INFO 


INFORMATION 


1 


L 


lEANUCOl 


000000 


0662 


000003 


000 loa 


00035643 


01024 000000 ABSENT 


SCTR=000102,00168,00316,Oa,04 





Figure 48. Edited Partitioned Directory Entry 



Unedited (Dump) Format 



The user may choose the unedited format. If this is the case, lEHLIST lists each 
member separately. 

Figure 49 shows how the information in Figure 47 is listed. 

Note: A listing such as that shown in Figure 47 can also be obtained by using 
lEBPTPCH (see "lEBPTPCH Program"). 



Listing a Volume 
Table of Contents 



Edited Format 



MEMB A TTR 

MEMB B TTR 

MEMB C TTR 

MEMB n TTR 



USER DATA 
USER DATA 
USER DATA 
USER DATA 



Figure 49. Sample Partitioned Directory Listing 



To correctly interpret user data information, the user must know the format of the 
partitioned entry. The formats of directory entries are discussed in OS System Control 
B/ocks, GC28-6628. 

lEHLIST can be used to list, partially or completely, entries in a specified volume 
table of contents (VTOG). The program lists the contents of selected data set control 
blocks (DSCBs) in edited or unedited form. 

Two edited formats are available. One is a comprehensive listing of the DSCBs in the 
VTOC. It provides the status and attributes of the volume, and describes in depth the 
data sets residing on the volume. This listing includes: 

• Logical record length and block size 

• Initial and secondary allocations 

• Upper and lower limits of extents 

• Alternate track information 

• Available space information, in detail 

• Option codes 

• Record formats 

A VTOC consists of as many as seven types of DSCBs, as follows: 

• Identifier DSCB — Format 1 

• Index DSCB — Format 2 

• Extension DSCB — Format 3 

• VTOC DSCB— Format 4 

• Free Space DSCB — Format 5 

• Shared Extent DSCB — Format 6 



218 Utilities (Release 21.7) 



• Free VTOC DSCB — Format 

The first DSCB in the VTOC (and on your listing) is always the VTOC (Format 4) DSCB, 
which defines the VTOC data set itself and the attributes of the volume on which it 
resides. The VTOC DSCB is always followed by the first Free Space (Format 5) DSCB, 
which describes the space that is available on the volume for allocation. More than 
one Free Space DSCB may be required to describe the available space on a volume 
because each Free Space DSCB describes only 26 extents. The first Free Space DSCB 
can be followed, in any order, by Format 1, 2, 3, or 6 DSCBs or by other Free Space 
DSCBs if there are more than 26 available extents on the volume. 

Identifier (Format 1) DSCBs describe a data set, its attributes, and its first three 
extents. 

Index (Format 2) DSCBs describe the index of a data set with indexed sequential 
organization. The Index DSCB is always chained from the Format 1 DSCB for the data 
set. 

Extension (Format 3) DSCBs describe the fourth through the sixteenth extents of a 
data set. The Extension DSCB is always chained from a Format 1 or a Format 2 DSCB. 

Shared Extent (Format 6) DSCBs describe an extent of one or more contiguous 
cylinders being shared by two or more data sets. The first Shared Extent DSCB is 
chained from the Format 4 DSCB. Subsequent Shared Extent DSCBs are chained from 
each previous Format 6 DSCB. 

Free VTOC records (called Format DSCBs) indicate that space is available for 
another DSCB. Free VTOC DSCBs, which are 140-byte records that consist of binary 
zeros, are written over with Format 1, 2, 3, and 6 DSCBs when a new data set is 
allocated, and with Format 5 DSCBs when space is released. The Free VTOC DSCB is 
not listed by lEHLIST. 

Figure 50 shows a sample listing of the edited format. This sample illustrates how 
each DSCB will appear on a listing, although in many cases the VTOC may not contain 
all possible types. The information is in columns, with the values or numbers 
appearing below each item's heading. 



SVSTEMS SUPPORT UTILITIES lEHLIST 



CONTENTS OF VTOC ON VOL EXAMPL 

FORMAT 4 DSCB NO AVAIL/MAX DSCB /MAX DIRECT NO AVAIL NEXT ALT 
DSCBS PER TRK BLK PER TRK ALT TRK TRK( C-H ) 
154 16 10 30 200 



FORMAT 6 
(C-H-R) 



LAST FMT 1 VTOC EXTENT 

DSCB( C-H-R )/LOW( C-H) HIGH(C-H) 
5 5 5 5 9 



FORMAT 5 DSCB 



FULL 

CYLS A 
3 3 



NUMBER OF TRKS IN ADDITION TO FULL CYLS IN THE EXTENT 



TRK 

ADDR 

110 



FULL 

CYLS 

189 



DSCB( C-H-R) 



_« DATA S ET NAME -— 

EXAMPLE . OF". COMBINED . FORMATS . ONE . AND . TWO 



2MIND( M-B-C-H )/3MIND( M-B-C-H )/L2MFN( C-H-R )/L3MIN( C-H-R )/CYLAD( M-B-C-H )/ADLIN( M-B-C-H )/ADHIN( M-B-C-H )/NOBYT/ NOTRK 
0000 0000 000 000 10 10 9 0000 10 10 9 70 

LTRAD( C-H-R )/LCYAD( C-H-R )/LMSAD( C-H-R )/LPRAD(M-B-C-H-R) /NOLFV /CYLOV/ TAGDT/ PRCTR / OVRCT/ R0RG1/PTRDS( C-H-R ) 
603 10 910001061 12 1 20 
UNABLE TO CALCULATE EMPTY SPACE. 



DATA SET NAME- 
EXAMPLE . OF . COMBINED . FORMATS . ONE 


.ANC 


ID 

.THREE 1 


SER NO SEQ NO 
EXAMPL 1 


CREDT 
36699 


EXPDT NO EXT DSORG 
27069 16 PS 


RECFM OPTCD BLKSIZE 
V 3504 


LRECL KEYLEN INITIAL 
3500 TRKS 


ALLOC 2ND ALLOC/LAST BLK PTR( T-R-L 
1 15 1 1723 


USED PDS BYTES 


FMT 


2 OR 3( C-H-R )/DSCB( C-H 
5 6 5 


EXTENTS NO 

3 
6 
9 
12 
15 


LOW(C- 



1 
1 
1 


H) 
1 
4 
7 

3 
6 


HIGH(C-H) 
1 
4 

7 

1 
1 3 
1 6 

-ON THE ABOVE 


NO LOW( C-H ) 

1 2 

4 5 

7 8 

10 1 1 

13 1 4 

DATA SET, THERE 


HIGHIC- 




1 
1 

ARE 


H ) NO LOW( C-H ) 
2 2 3 
5 5 6 
8 8 9 
1 11 12 
4 14 15 

EMPTY TRACK(S). 


HIGH(C-H) 
3 
6 

9 

1 2 
1 5 



THERE ARE 192 EMPTY CYLINDERS PLUS 3 EMPTY BRACKS ON THIS VOLUME 

THERE ARE 154 BLANK DSCBS IN THE VTOC ON THIS VOLUME 



Figure 50. Sample Printout of a Volume Table of Contents 
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Unedited (Dump) Format 



Input and Output 



Control 



Job Control Statements 



The second edited format is an abbreviated description of the data sets. It is provided 
by default when no format is requested specifically. It provides the following 
information: 

• Data set name 

• Creation date (dddyy) 

• Expiration date (dddyy) 

• Password indication 

• Organization of the data set 

• Extent(s) 

• Volume serial number 

The last line in the listing indicates how much space remains in the VTOC. 

This option produces a complete hexadecimal listing of the DSCBs in the VTOC. The 
listing is in an unedited dump form, requiring the user to know the various formats of 
applicable DSCBs. The VTOC overlay for lEHLIST listings of VTOCs in DUMP format 
(Order Number ZM08-0033) is useful in identifying the fields of the DSCBs. 

Refer to OS System Control Blocks, GC28-6628 for a discussion of the various formats 
that data set control blocks can assume. 

lEHLIST uses the following input: 

• One or more source data sets that contain the data to be listed. The input data 
set(s) can be: (1) a VTOC data set, (2) a partitioned data set, or (3) a catalog data 
set (SYSCTLG). 

• A control data set, which contains utility control statements that are used to control 
the functions of lEHLIST. 

lEHLIST produces as output a message data set, which contains the result of the 
lEHLIST operations. The message data set includes the listed data and any error 
messages. 

lEHLIST produces a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 08, which indicates that an error condition caused a specified request to be 
ignored. Processing continues. 

• 12, which indicates that a permanent input/output error occurred. The job is 
terminated. 

• 16, which indicates that an unrecoverable error occurred while reading the data 
set. The job is terminated. 

lEHLIST is controlled by job control statements and utility control statements. The job 
control statements are used to execute or invoke lEHLIST and to define the data set 
used and produced by lEHLIST. 

Utility control statements are used to control the functions of the program and to 
define those data sets or volumes to be modified. 

Table 42 shows the job control statements necessary for using lEHLIST. 

The minimum region size that can be specified for lEHLIST when an overlay structure 
is not used is 44K. 

The "anynamel" DD statement can be entered: 

//anynamel DD UNIT = xxxx, VOLUME = SER = xxxxxx.DISP = OLD 

The UNIT and VOLUME parameters define the device type and volume serial number. 
The DISP = OLD specification prevents the inadvertent deletion of the data set. This 
statement is arbitrarily assigned the ddname DDl in the lEHLIST examples. 

When deferred mounting is required, the "anyname2" DD statement can be entered: 

//anyname2 DD UNIT = (xxx„ DEFER), VOLUME = (PRIVATE,. ..),DISP = OLD 

See "Appendix C: DD Statements for Defining Mountable Devices" for information on 
defining mountable devices. This statement is arbitrarily assigned the ddname DD2 in 
the lEHLIST examples. Statements defining additional mountable devices are assigned 
ddnames DD3, DD4, etc. 
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Restrictions 



FARM Information on 
the EXEC Statennent 



Utility Control Statements 



USTCTLG Statement 



Table 42. lEHLIST Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = lEHLIST) or, if the job control statements 

reside in a procedure library, the procedure name. Additional FARM 
information can be specified to control the number of lines printed per page. 
See "PARM Information on the EXEC Statement" below. 

SYSPRINT DD Defines a sequential message data set. 

anynamel DD Defines a permanently mounted volume. 

anyname2 DD Defines a mountable device type. 

SYSIN DD Defines the control data set. The control data set normally follows the job 

control language in the input stream; however, it can be defined as an 
unblocked sequential data set or member of a procedure library. 

With the exception of the SYSIN and SYSPRINT DD statements, all DD statements in 
this table are used as device allocation statements, rather than as true data definition 
statements. 

• The block size for the SYSPRINT data set must be a multiple of 121. The block size 
for the SYSIN data set must be a multiple of 80. Any blocking factor can be 
specified for these block sizes. 

• An anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. (The system residence volume is considered to 
be a permanently mounted volume.) 

• An anyname2 DD statement must be included for each mountable device to be 
used in the job step. 

• Because lEHLIST modifies the internal control blocks created by device allocation 
DD statements, lEHLIST job control statements must not include the DSNAME 
parameter. (All data sets are defined explicitly or implicitly by utility control 
statements.) 

• When lEHLIST is dynamically invoked in a job step containing another program, the 
DD statements defining mountable devices for lEHLIST must be included in the job 
stream prior to DD statements defining data sets required by the other program. 

• lEHLIST cannot support empty space calculations for data sets allocated in blocks 
when the blocksizes are approximately the same size or are larger than the 
tracksize. The empty block calculation gives only approximate indications of 
available space. When lEHLIST cannot supply an approximate number, the "Unable 
to Calculate" message is issued. 

• lEHLIST specifications do not allow for protection of the object being listed. If 
another program updates a block of the data set just prior to lEHLIST reading the 
data set, a message (IEH105I or IEH108I) may be issued. In the case of LISTVTOC, 
the output produced by lEHLIST may be incorrect. When this happens, you should 
rerun tlie job. 

Additional information can be specified in the PARM parameter of the EXEC statement 
to control the number of lines printed per page. The PARM parameter can be coded: 

PARM = 'LINECNT = xx' 

The LINECNT parameter specifies the number of lines, xx, to be printed per page; xx is 
a decimal number from 01 through 99. If LINECNT is not specified, 58 lines are 
printed per page. The PARM field cannot contain embedded blanks, zeros, or any 
other PARM keywords, or the default of 58 is used. 

lEHLIST is controlled by the following utility control statements: 

• LISTCTLG statement, which is used to request a listing of all or part of a catalog. 

• LISTPDS statement, which is used to request a directory listing of one or more 
partitioned data sets. 

• LISTVTOC statement, which is used to request a listing of all or part of a volume 
table of contents. 

The LISTCTLG statement is used to request a listing of either the entire catalog or a 
specified portion of the catalog (SYSCTLG data set). The listing includes the 
fully-qualified name of each applicable cataloged data set and the serial number of 
the volume on which it resides. Empty index levels are not listed. 
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LISTPDS Statement 



LISTVTOC Statement 



The format of the LISTCTLG statement Is: 

r""[/abe/]"uSTCfLG [m='cfeWce = serSo^ —— ™.,.-..,^.-. ........ 

\ [,NODE «= name} 

where: 

VOL = device = serial 

specifies the device type and volume serial number of the control volume on which 
the specified portion of the catalog resides. If VOL is omitted, the catalog is 
assumed to reside on the system residence volume. 

NODE = name 

specifies a qualified name. All data set entries whose names are qualified by this 
name are listed. If NODE is omitted, all data set entries are listed. 

Note: General catalog information (one-level data sets and CVOL pointers) is printed 
prior to the printing of an entire catalog or node. 

The LISTPDS statement is used to request a directory listing of one or more 
partitioned data sets that reside on the same volume. 

The format of the LISTPDS statement is: 



I [/abe/] LISTPDS DSNAME = (name[,name]...) 

\ [,VOL = device = serial] 

: {.DUMP } 

; {.FORMAT} 

where: 

DSNAME = (name[,name]...) 

specifies the fully-qualified names of the partitioned data sets whose directories 
are to be listed. A maximum of ten names is allowed. If the list consists of a single 
name, the parentheses can be deleted. 

VOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
partitioned data sets reside. If VOL is omitted, the data sets are assumed to reside 
on the system residence volume. 

DUMP 

specifies that the listing is to be in unedited, hexadecimal form. 

FORMAT 

specifies that the listing is to be edited for each directory entry. 

Before printing the directory entries on the first page, an index is printed explaining 
I the attributes (field 3) and other information (field 10). ATTRIBUTE INDEX explains 
each attribute bit; OTHER INFORMATION INDEX explains scatter and overlay format 
data as it appears in the listing. 

Note: The LISTPDS statement may be used only on a partitioned data set whose 
members have been created by the linkage editor. Members that have not been 
created by the linkage editor cause their directory entries to be listed in unedited 
(DUMP) format. 

The LISTVTOC statement is used to request a partial or complete listing of the entries 
in a specified volume table of contents. 

The format of the LISTVTOC statement is: 



[label] LISTVTOC 



{DUMP } 
{FORMAT) 

[.DATE = dddyy] 

[,VOL = device = serial] 

[.DSNAME = {name[,name]...) 



where: 



DUMP 

specifies that the listing is to be in unedited, hexadecimal form. If both DUMP and 
FORMAT are omitted, an abbreviated edited format is generated by default. 

FORMAT 

specifies that a comprehensive edited listing is to be generated. If both FORMAT 
and DUMP are omitted, an abbreviated edited format is generated by default. 
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DATE = dddyy 

specifies that each entry that expires before this date is to be flagged with an 
asterisk (*) in the listing. This parameter applies only to the abbreviated edited 
format. The date is represented by ddd, the day of the year, and yy, the last two 
digits of the year. If DATE is omitted, no asterisks appear in the listing. 

VOL = dewce = serial 

specifies the device type and volume serial number of the volume whose table of 
contents is to be listed. If VOL is omitted, the system residence volume is assumed. 

DSNAME = (name[,name]...) 

specifies the fully-qualified names of the data sets whose entries are to be listed. A 
maximum of ten names is allowed. If DSNAME is omitted, the entire volume table of 
contents is listed. 

The following examples illustrate some of the uses of lEHLIST. Table 43 can be used 
as a quick reference guide to lEHLIST examples. The numbers in the "Example" 
column point to examples that follow. 



Table 43. lEHLIST Example Directory 
Operation Device Comments 



Example 



lEHLIST Example 1 



LIST 



LIST 



LIST 



LIST 



2314 Disk, 
system output 
device 

2314 Disk, 
system residence 
device, system 
output device 

2314 or 2319 
Disk.i 3330 
Disk system 
output device 

2314 Disk, 
system output 
device 



Source catalog is to be listed on the 
system output device. 

Three catalogs and part of a fourth 
are to be listed on the system 
output device. 

Three partitioned directories are to 
be listed on the system output device. 



Volume table of contents is to be 
listed in edited form; selected 
data set control blocks are listed 
in unedited form. 



1 Note that the 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 2314 
in the control statement. 

Note: In the lEHLIST examples, the EXEC statement and the SYSPRINT DD statement 
can be replaced with the following job control statement: 

// EXEC PROC = LIST 

The EXEC statement invokes the following IBM-supplied cataloged procedure: 

//LIST EXEC PGM = lEHLIST.REGIGN = 44K 

//DDSRV DD VOLUME = REF = SYSl.SVCLIB.DISP = OLD 

//SYSPRINT DD SYSOUT = A 

In this example a catalog residing on a 2314 volume (231400) is to be listed. 

The example follows: 

//LISTCAT JOB 09#550,BLUE 

// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//SYSIN DD * 

LISTCTLG VOL=23 14=23 1400 
/* 

The control statements are discussed below: 

• DD2 DD defines a mountable device on which the volume containing the source 
catalog is mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• LISTCTLG defines the source volume and specifies the list operation. 
Note: The data set name of the catalog data set is SYSCTLG. 
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lEHLIST Example 2 



lEHLIST Example 3 



In this example a catalog residing on the system residence volume, two catalogs 
residing on 2314 volumes, and a portion of a catalog residing on a 2314 volume, are 
to be listed. 

The example follows: 

//LISTCATS JOB 09#550,BLUE 

// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330,VOLUME=SER=11 1 1 1 1 ,DISP=OLD 

//DD2 DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231400 ) ) 

//SYSIN DD * 

LISTCTLG 

LISTCTLG VOL=23 14=23 1400 

LISTCTLG VOL=23 14=23 1401 

LISTCTLG VOL=23 1 4=23 1402, NODE=A . B . C 
/* 

The control statements are discussed below: 

• DDl DD defines a system residence device. (The first catalog to be listed resides 
on the system residence volume.) 

• DD2 DD defines a mountable device on which each 2314 volume is mounted as it is 
required by the program. 

• SYSIN DD defines the control data set, which follows in the input stream. 

o The first LISTCTLG statement indicates that the catalog residing on the system 
control volume is to be listed. 

• The second and third LISTCTLG statements identify two 2314 disk volumes 
containing catalogs to be listed. 

• The fourth LISTCTLG statement identifies a 2314 volume containing a catalog that 
is to be partially copied. All data set entries whose beginning qualifiers are "A.B.C" 
are copied. 

In this example, a partitioned directory existing on the system residence volume is to 
be listed. In addition, two partitioned directories existing on a 2314 or 2319 volume 
are to be listed. Note that the 2319 disl< is functionally equivalent to the 2314 disk; to 
use the 2319 specify 2314 in the control statement. 

The example follows: 

//LISTPDIR JOB 09#550,BLUE 
// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 



//DDl DD 
//DD2 DD 
//SYSIN DD 

LISTPDS 

LISTPDS 
/* 

The control statements are discussed below: 



UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

* 

DSNAME=PARSET1 

DSNAME=( PARTI ,PART2 ) ,VOL=231 4=23 1 400 



DDl DD defines the system residence device. 

DD2 DD defines a mountable device on which a 2314 volume (231400) is to be 
mounted. 

SYSIN DD defines the control data set, which follows in the input stream. 

The first LISTPDS statement indicates that the partitioned data set directory 
belonging to data set PARSETl is to be listed. This data set exists on the system 
residence volume. 

The second LISTPDS statement indicates that partitioned directories belonging to 
data sets PARTI and PART2 are to be listed. These data sets exist on a 2314 
volume (231400). 
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lEHLIST Example 4 In this example, a volume table of contents in edited form, is to be listed. The edited 

listing is supplemented by an unedited listing of selected data set control blocks. 

The example follows: 

//LISTVTOC JOB 09#550,BLUE 

// EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//SYSIN DD * 

LISTVTOC FORMAT, VOL=23 14=23 1400 

LISTVTOC DUMP , VOL=23 1 4=23 1 400 , DSNAME=( SET1 , SET2 , SET3 ) 
/* 

The control statements are discussed below: 

• DD2 DD defines a mountable device on which the volume containing the specified 
volume table of contents is to be mounted. 

• SYSIN DD defines the control data set which follows in the input stream. 

• The first LISTVTOC statement indicates that the volume table of contents on the 
specified 2314 volume is to be listed in edited form. 

• The second LISTVTOC statement indicates that the data set control blocks 
representing data sets SETl, SET2, and SET3 are to be listed in unedited form. 
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lEHMOVE Program 



lEHMOVE is a system utility used to move or copy logical collections of operating 
system data. (See "Introduction" for general system utility information.) 

lEHMOVE can be used to move or copy: 

• A data set residing on from one to five volumes. 

• A group of cataloged data sets. 

• A catalog, or portions of a catalog. 

• A volume of data sets. 

The scope of a basic move or copy operation can be enlarged by: 

• Merging members from two or more partitioned data sets. 

• Including or excluding selected members. 

• Renaming moved or copied members. 

• Replacing selected members. 

• Including or excluding data sets from a move or copy operation. 

If, for some reason, lEHMOVE is unable to successfully move or copy specified data, 
an attempt is made to reorganize the data and place it on the specified output device. 
The reorganized data — called an unloaded data set — is a sequential data set consisting 
of 80-byte blocked records that contain the source data and control information for 
subsequently reconstructing the source data as it originally existed. 

When an unloaded data set is moved or copied to a device that will support the data in 
its true form, the data is automatically reconstructed. For example, if the user 
attempts to move a partitioned data set to a tape volume, the data is unloaded onto 
that volume. The user can re-create the data set simply by moving the unloaded data 
set to a direct access volume. 

A move operation differs from a copy operation in that a move operation scratches 
source data if the data set resides on a direct access source volume and the 
expiration data has occurred, while a copy operation leaves source data intact. In 
addition, for cataloged data sets, a move operation updates the catalog to refer to the 
moved version (unless otherwise specified), while a copy operation leaves the catalog 
unchanged. 

Space for a new data set on a direct access device can be allocated by the user in a 
previous job step or by lEHMOVE in an lEHMOVE job step. 

Space can be allocated by the user in a previous job step by using a DD statement 
that specifies the amount of space required. If, however, a data set that contains 
location-dependent information (for instance, a data set with the unmovable attribute) 
is being moved or copied, the user should allocate space for the receiving data set 
using absolute track allocation. This ensures that the data is placed in the same 
relative location on the receiving volume as on the source volume (provided the 
device types of source and receiving volumes are the same). Unmovable data is 
moved or copied even when space allocation was not made before the lEHMOVE job 
step. No assumptions, however, can be made as to whether the location-dependent 
information is correct. (The lEHIOSUP program can be used to update the new version 
of a SYSl.SVCLIB after it has been moved or copied into a space which was not 
preallocated.) 

Space for a new data set cannot be allocated by the user under the following 
circumstances: 

• When the organization of the data set to be moved or copied is direct and the data 
set is not to be unloaded, lEHMOVE cannot determine if the new data set is empty. 

• When a partitioned data set is being moved or copied as part of a move or copy 
volume operation and the data set is not to be unloaded. If the user does 
preallocate a partitioned data set in this case, no merging takes place. 

If lEHMOVE performs the space allocation for the new data set, the space requirement 
information of the old data set (if available) is used. This space requirement 
information is obtained from the DSCB of the source data set, if it is on a direct 
access device, or from the control information in the case of an unloaded data set. 
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If space requirement information is available, lEHMOVE uses this information to derive 
an allocation of space for the receiving volume, taking into account all differences in 
device characteristics, such as track capacity and overhead factors. However, when 
data sets with variable or undefined record formats are being moved or copied 
between unlike devices, no assumption can be made about the space that each 
individual record needs on the receiving device. 

In general, when variable or undefined record formats are to be moved or copied, 
lEHMOVE attempts to allocate space on the assumption that all blocks in the data set 
are of the maximum length. This can cause the following situations when moving or 
copying between unlike devices: 

• When moving or copying from a device with a relatively small block overhead to a 
device with a larger block overhead, too much space is allocated. 

• When moving or copying from a device with a large block overhead to a device with 
a smaller block overhead, too little space might be allocated. In this case, the user 
should preallocate the data set with enough primary or secondary space. 

If the data set to be moved or copied is on neither a direct access device nor an 
unloaded data set (for instance, a sequential data set on a tape volume), lEHMOVE 
uses a default allocation of approximately 72,500 bytes of primary space plus 36,250 
bytes of secondary space. Any default space that is unused after the data set has 
been moved or copied is released. 

Note: Data sets with direct organization and variable record format always have the 
same amount of direct access space allocated by lEHMOVE. This practice preserves 
any relative track addressing system that might exist within the data sets. 

A move or copy operation results in: (1) a moved or copied data set, (2) no action, or 
(3) an unloaded version of the source data set. These results depend upon the 
compatibility of the source and receiving volumes with respect to: 

• Size of the volumes. 

• Data set organization (sequential, partitioned, or direct access). 

• Movability of the source data set. 



Allocation of space on the receiving volume. 



Two volumes are compatible with respect to size if (1) the source record size does not 
exceed the receiving track size or (2) the receiving volume supports the track 
overflow feature and the output is to be written with track overflow. (Refer to "Job 
Control Statements" for notes on the track overflow feature.) When using direct 
access organization, two volumes are compatible with respect to size if the source 
track capacity does not exceed the receiving track capacity. Direct access data sets 
moved or copied to a smaller device type or tape are unloaded. If the user wishes to 
load an unloaded direct access data set, it must be loaded to the same device type 
from which it originally was unloaded. 

If the UNLOAD keyword is specified, a data set can be unloaded even though the 
receiving volume and data set organization would allow for a normal copy or move 
operation. (See "Utility Control Statements" in this chapter.) 

Table 44 shows the results of move and copy operations when the receiving volume is 
a direct access volume that is compatible in size with the source volume. The 
organization of the source data set set is shown along with the characteristics of the 
receiving volume. 

Table 45 shows the results of move and copy operations when the receiving volume is 
a direct access volume that is not compatible in size with the source volume. The 
organization of the source data set is shown along with the characteristics of the 
receiving volume. 

Table 46 shows the results of move and copy operations when the receiving volume is 
not a direct access volume. The organization of the source data set is shown along 
with the characteristics of the receiving volume. 
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Table 44. Move and Copy Operations — Direct Access Receiving Volume with Size 
Compatible with Source Volume 



Receiving Volume 
Ciiaracteristics 

Space allocated 
by lEHMOVE 
(movable data) 

Space allocated 
by lEHMOVE 
(unmovable data) 

Space previously 
allocated, as yet 
unused 

Space previously 
allocated, partially 
used 



Sequential 
moved or copied 

moved or copied 

moved or copied 

no action 



Partitioned 
moved or copied 

moved or copied 

moved or copied 



moved or copied 
(merged) 



Direct Access 
moved or copied 

no action 

no action 

no action 



Table 45. Move and Copy Operations — Direct Access Receiving Volume with Size 
Incompatible with Source Volume 



Receiving Volume 
Characteristics 


Sequent/a/ 


Partitioned 


Direct Accessf 


Space allocated 
by lEHMOVE 


unloaded 


unloaded 


unloaded 


Space previously 
allocated, as yet 
unused 


unloaded 


unloaded 


no action 


Space previously 
allocated, partially 
used 


no action 


no action 


no action 




Table 46. Move and Copy Operations- 


-Nondirect Access Receiving Volume 


Receiving Volume 
Characteristics 


Sequential 


Partitioned 


Direct Access 


Movable data 


moved or copied 


unloaded 


unloaded 


Unmovable data 


unloaded 


unloaded 


no action 



lEHMOVE does not scratch data sets if the expiration date has not occurred. 
lEHPROGM can be used to scratch these data sets (see the chapter "lEHPROGM 
Program"). 

Note: When space Is previously allocated for a data set that is to be unloaded, the 
data set should be sequentially organized, as is the case for unloaded data sets. 

If a move or copy operation is unsuccessful, the source data remains intact. 

If a move or copy operation is unsuccessful and space was allocated by lEHMOVE, all 
data associated with that operation is scratched from the receiving direct access 
volume. If the receiving volume was tape, it will contain a partial data set. 

If a move or copy operation is unsuccessful and space was previously allocated, no 
data is scratched from the receiving volume. If, for example, lEHMOVE moved 104 
members of a 105-member partitioned data set and encountered an input/output 
error while moving the 105th member: 

• The entire partitioned data set is scratched from the receiving volume if space was 
allocated by lEHMOVE. 

• No data is scratched from the receiving volume if space was previously allocated. 
In this case, after determining the nature of the error, the user need move only the 
105th member into the receiving partitioned data set. 

When moving or copying a data set group or a volume containing password -protected 
data sets, the user must provide the password each time a data set is opened or 
scratched. 
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Reblocking 



Moving or Copying 
a Data Set 



lEHMOVE always moves or copies any user labels associated witli an input data set. 
lEIHIVIOVE does not take exits to a user's label processing routines. 

When moving or copying a password -protected data set, the reproduced data set is 
protected in the same way as the source data set, unless a different protection level is 
established through preallocatlon. 

It is your responsibility to update your system's PASSWORD data set. This can be 
done with the RENAIVIE function of lEHMOVE. 

Note: If a data set that has only user trailer labels is to be moved from a tape volume 
to a direct access volume, space must be previously allocated on the direct access 
volume to ensure that a track is reserved to receive the user labels. 

Data sets with fixed or variable records can be reblocked to a different block size by 
previously allocating the desired block size on the receiving volume. No reblocking can 
be performed when loading or unloading. 

When moving or copying data sets with undefined record format and reblocking to a 
smaller block size (that is, transferring records to a device with a track capacity 
smaller than the track capacity of the original device), the user must make the block 
size for the receiving volume equal to or larger than the size of the largest record in 
the data set being moved or copied. 

lEHMOVE can be used to move or copy sequential, partitioned, and direct access 
data sets, as follows: 

• A sequential data set can be: (1) moved from one direct access or nondirect 
access volume to another (or to the same volume provided that it is a direct access 
volume) or (2) copied from one direct access or nondirect access volume to 
another (or to the same volume provided that the data set name is changed and 
the receiving volume is a direct access volume). 

• A partitioned data set can be: (1) moved from one direct access volume to another 
(or to the same volume) or (2) copied from one direct access volume to another 
(or to the same volume provided that the data set name is changed). 

• A direct access data set can be moved or copied from one direct access volume to 
another provided that the receiving device type is the same device type or a larger 
device type and that the record size does not exceed 32K. 

In addition, lEHMOVE can be used to move or copy multivolume data sets. To move or 
copy a multivolume data set, specify the complete volume list in the VOL = SER 
parameter on the DD statement. To move or copy a data set that resides on more 
than one tape volume, specify the volume serial numbers of all the tape volumes and 
the sequence numbers of the data set on the tape volumes in a utility control 
statement. (You must specify the sequence number even if the data set to be moved 
or copied is the only data set on a volume.) To move or copy a data set to more than 
one tape volume, follow the same procedure as for the list field of the 
TO = device = list parameter in the utility control statement. 

For MOVE/COPY operations on a data set that resides on multiple volumes, all volume 
serial numbers involved should be given in the list field of the 

FROM/TO = dewce = list parameter of the utility control statement. The volume serial 
numbers must also appear in the list field of the VOLUME = SER = list parameter of 
the DD statement indicating where the text is to be placed. On that same DD 
statement, especially when operating on a BDAM data set, you should code the UNIT 
parameter as follows: UNIT = (devicetype,?). 

A data set with the unmovable attribute can be moved or copied from one direct 
access volume to another or to the same volume provided that space has been 
previously allocated on the receiving volume. Change the name of a data set to move 
or copy it to the same volume. SVCLIB can be moved or copied to another location on 
the system residence volume, provided that space is available and that space has 
been previously allocated on that volume. lEHPROGM must be used immediately after 
such a move operation to rename the moved version SYS 1. SVCLIB. After such a copy 
operation, lEHPROGM must be used to scratch the old version and to rename the 
copied version. In either case, lEHIOSUP must be used immediately after the 
lEHPROGM step to update the new version of SVCLIB. 

When moving or copying a BDAM data set from one device to another device of the 
same type, relative track and relative block integrity are maintained. 

When moving or copying a BDAM data set to a larger device, relative track integrity is 
maintained for data sets with variable or undefined record formats; relative block 
integrity is maintained for data sets with fixed record formats. 
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When moving or copying a BDAM data set to a smaller device or a tape, the data set 
is unloaded. An unloaded data set is loaded only when it is moved or copied to the 
same device type from which it was unloaded. 

Table 47 shows basic and optional move and copy operations for sequential and 
partitioned data sets. 

lEHMOVE moves or copies partitioned members in the order in which they appear in 
the partitioned directory. That is, moved or copied members are placed in collating 
sequence on the receiving volume. 



Table 47. Moving and Copying Sequential and Partitioned Data Sets 



Operation Basic Actions 



Move 
Sequential 

Move 
Partitioned 



Copy 



Copy 
Partitioned 



Move the data set. For direct access, 
scratch the source data. For cataloged 
to refer to the moved data set. 

Move the data set. For direct access, 
scratch the source data. For cataloged 
data sets, update the catalog to refer 
to the moved data set. 



Copy the data set. The source data set 
is not scratched. The catalog Is not 
updated to refer to the copied data set. 

Copy the data set. The source data is 
not scratched. The catalog is not 
updated to refer to the copied data 
set. 



Optional Actions 

Prevent automatic cataloging of 
the moved data set. Rename the 
moved data set. 

Prevent automatic cataloging of 
the moved data set. Rename the 
moved data set. Re-allocate 
directory space. (Not possible if 
the space previously allocated is 
partially used.) Perform a merge 
operation using members from two 
or more data sets. Move only 
selected members. Replace members. 
Unload the data set. 

Uncatalog the source data set. 
Catalog the copied data set on 
the receiving volume. Rename 
the copied data set. 

Uncatalog the source data set. 
Catalog the copied data set on 
the receiving volume. Rename 
the copied data set. Re-allocate 
directory space. (Not possible 
if the space previously allocated 
is partially used.) Perform a 
merge operation using members from 
two or more data sets. Copy only 
selected members. Replace members. 
Unload the data set. 



Figure 51 shows a copied partitioned data set. Note that the members are copied in 
the order in which they appear in the partitioned directory. lEBCOPY can be used to 
copy data sets whose members are not to be collated. 



Source data set 



Copied data set 




B J I D 

Figure 51. Partitioned Data Set Before and After an lEHMOVE Copy Operation 



Members that are merged into an existing data set are placed, in collating sequence, 
after the last member in the existing data set. 

Figure 52 shows members from one data set merged into an existing data set. Note 
that members A, C, and G from the existing data set are copied to the receiving 
volume before members B and F are copied from the source data set. Members B and 
F are copied in collating sequence. 

Figure 53 shows how members from two data sets are merged into an existing data 
set. Members from additional data sets can be merged in a like manner. Note that 
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Source data set 



Moving or Copying 
a Group of Cataloged 
Data Sets 



Existing data set 
prior to merge 



Existing data set 
after merge 





Figure 52. Merging Two Data Sets Using lEHMOVE 



members A, C, and G are copied from tlie existing data set before any members are 
copied from tlie source data sets. Members F, B, D, and E from tlie source data sets 
are copied in collating sequence. 

Source data sets 



Existing data set 
prior to merge 



Existing data set 
after merge 





members 

Figure 53. Merging Three Data Sets Using lEHMOVE 



lEHMOVE can be used to move or copy a group of data sets that are cataloged on 
the same volume and whose names are qualified by one or more identical names. 
For example, a group of data sets qualified by the name A.B can include data sets 
named A.B.D and A.B.E, but could not include data sets named A.C.D or A.D.F. 

Additional data sets not belonging to the specified data set group can be included in 
the move or copy operation; data sets belonging to the group can be excluded. 

If a group of data sets is moved or copied to magnetic tape, the data sets must be 
retrieved one by one by data set name and file sequence number, or by file sequence 
number for unlabeled or nonstandard labeled tapes. 

lEHLIST can be used to determine the structure of the catalog. 

Table 48 shows basic and optional move and copy operations for a group of cataloged 
data sets. 
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Table 48. Moving and Copying a Group of Cataloged Data Sets 



Moving or Copying 
a Catalog 



Operation Basic Actions 

Move group Move the data set group (excluding 

of cataloged password-protected data sets) to the 

data sets specified volumes. Scratch the source 

data sets (direct access only). 
The catalog is not updated to refer to 
moved data sets. Merging is not done. 

Copy group Copy the data set group (excluding 

of cataloged password-protected data sets.). Source 

data sets data sets are not scratched. The 

catalog is not updated to refer to 
copied data sets. Merging is not done. 



Optional Actions 

Prevent updating of the catalog. 
Include password-protected data 
sets in the operation. Include 
additional data sets in the 
operation. Exclude data sets from 
the operation. Unload data sets. 

Include password-protected data 
sets in the operation. Uncatalog 
the source data sets. Catalog 
the copied data sets on the 
receiving volumes. Include 
additional data sets in the 
operation. Unload a data set or 
sets. 



lEHMOVE can be used to move or copy a catalog or portions of a catalog without 
copying the data sets represented by the cataloged entries. The SYSCTLG (system 
catalog) data set need not be defined on the receiving volume before the operation. 
If, however, SYSCTLG was defined before the operation, the data set organization 
must not have been specified in the DCB field. Moved or copied entries are merged 
with any existing entries on the receiving volume. Note that the receiving volume must 
be a direct access volume unless the catalog is to be unloaded. 

Table 49 shows basic and optional move and copy coperations for the catalog. 



Moving or Copying a 
Volume of Data Sets 



Table 49. Moving and Copying the Catalog 

Operation Basic Actions 

Move catalog Move entries from the catalog to the 
specified direct access volume. 
Scratch the source volume. 



Copy catalog Copy entries from the catalog to the 
specified direct access device. The 
source catalog is not scratched. 



Optional Actions 

Exclude selected entries from 
operation. Move an unloaded 
version of the catalog. Unload 
the catalog to the magnetic 
tape volume. 

Exclude selected entries from 
the operation. Copy an unloaded 
version of the catalog. Unload 
the catalog to a tape volume. 



lEHMOVE can be used to move or copy the data sets of an entire direct access 
volume to another volume or volumes. A move operation differs from a copy operation 
in that the move operation scratches source data sets, while the copy operation does 
not. For both operations, any cataloged entries associated with the source data sets 
remain unchanged. lEHPROGM can be used to uncatalog all of the cataloged data sets 
and recatalog them according to their new location. 

If the source volume contains a SYSCTLG data set, that data set is the last to be 
moved or copied onto the receiving volume. 

If a volume of data sets is moved or copied to tape, the data sets must be retrieved 
one by one by data set name and file sequence number, or by file sequence number 
for unlabeled or nonstandard labeled tapes. 

When copying a volume of data sets, the user has the option of cataloging all source 
data sets in a SYSCTLG data set on a receiving volume. However, if a SYSCTLG data 
set exists on the source volume, error messages indicating that an inconsistent index 
structure exists are generated when the source SYSCTLG entries are merged into the 
SYSCTLG data set on the receiving volume. 

The move volume feature does not merge partitioned data sets. If a data set on the 
volume to be moved or copied has a name identical to a data set name on the 
receiving volume, the data set is not moved, copied, or merged onto the receiving 
volume. 

Table 50 shows basic and optional move and copy operations for a volume of data 
sets. 
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Table 50. Moving and Copying a Volume of Data Sets 



Moving or Copying 
Direct Data Sets with 
Variable Spanned Records 



Input and Output 



Control 



Operation Basic Actions 

Move a volume Move all data sets not protected by a 
of data sets password to the specified direct access 

volumes. Scratcii the source data sets 
for direct access volumes. The catalog 
is not updated. 

COPY a volume Copy all data sets not protected by a 
of data sets password to the specified direct access 

volume. The source data sets are not 

scratched. 



Optional Actions 

Include password -protected data 
sets in the operation. Move to a 
tape volume. 



Include password-protected data 
sets in the operation. Catalog all 
copied data sets on the receiving 
volume (direct access only). 
Copy to a tape volume. 



lEHMOVE can be used to move or copy direct data sets with variable spanned 
records from one direct access volume to a compatible direct access volume, 
provided that the record size does not exceed 32K. 

Because a direct access data set can reside on one to five volumes (all of which must 
be mounted during any move or copy operation), it is possible for the data set to span 
volumes, i-iowever, single variable spanned records are contained on one volume. 

Relative track integrity is preserved in a move or copy operation for spanned records. 
Moved or copied direct access data sets occupy the same relative number of tracks 
that they occupied on the source device. 

If a direct data set is unloaded (moved or copied to a smaller device or tape), it must 
be loaded back to the same device type from which it was originally unloaded. 

When moving or copying variable spanned records to a larger device, record segments 
are combined and respanned if necessary. Because the remaining track space is 
available for new records, variable spanned records are unloaded before being moved 
or copied back to a smaller device. 

If a user wishes to create a direct data set without using data management BDAM 
macros, all data management specifications must be followed. Special attention must 
be given to data management specifications for RO track capacity record content, 
segment descriptor words, and the BFTEK = R parameter. 

When moving or copying a multivolume data set, the secondary allocation for direct 
data sets should be at least two tracks. (See the "WRITE SZ" macro instruction in OS 
Supervisor & Data Mar)agement Macro Instructions, GC28-6647.) 

lEHMOVE uses the following input: 

• One or more data sets, which contain the data to be moved, copied, or merged into 
a output data set. 

• A control data set, which contains utility control statements that are used to control 
the functions of the program. 

• A work data set, which is a work area used by lEHMOVE. 
lEHMOVE produces the following output: 

• An output data set, which is the result of the move, copy, or merge operation. 

• A message data set, which contains informational messages (for example, the 
names of moved or copied data sets) and error messages, if applicable. 

lEHMOVE produces a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• GO, which indicates successful completion. 

• 04, which indicates that a specified function was not completely successful. 
Processing continues. 

• 08, which indicates a condition from which recovery is possible. Processing 
continues. 

• 12, which indicates an unrecoverable error. The job step is terminated. 

lEHMOVE is controlled by job control statements and utility control statements. The 
job control statements are used to execute or invoke the program, define the devices 
and volumes used and produced by lEHMOVE, and prevent data sets from being 
deleted inadvertently. 
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utility control statements are used to control the functions of the program and to 
define those data sets or volumes that are to be used. 

Job Control Statements Table 51 shows the job control statements necessary for using lEHMOVE. 

Table 51. lEHMOVE Job Control Statements 

Statement Use 

JOB Iniiiates the job. 

EXEC Specifies the program name (PGM = lEHMOVE) or, if the job control statements 

reside in a procedure library, the procedure name. This statement can include 
optional PARM information; see "PARIVl Information on the EXEC Statement" 
below. 

SYSPRINT DD Defines a sequential message data set. The data set can be written onto a system 
output device, a magnetic tape volume, or a direct access volume. 

SYSUTl DD Defines a volume on which a work data set required by lEHMOVE is placed. 

anynamel DD Defines a permanently mounted volume. (The system residence volume is 
considered to be a permanently mounted volume.) 

anyname2 DD Defines a mountable device type. 

tape DD Defines a tape volume to be used when moving or copying from or to a 7-track 

tape volume, a 9-track tape volume not having standard labels, or a 1600 bits 
per inch, 9-track tape volume on a single-density drive, or when copying to an 
800 bits per inch tape on a dual-density drive. 

SYSIN DD Defines the control data set. The data set, which contains utility control 

statements, usually follows the job control statements in the input stream; 
however, it can be defined either as an unblocked sequential data set or as a 
member of a procedure library. 

The minimum region size that can be specified for the execution of lEHMOVE is 16K + 
b, where b is the largest block size in the job step rounded to the next higher 2K. 

The SYSUTl DD statement can be coded: 

//SYSUTl DD UNIT = xxxx, VOLUME = SER = xxxxxx,DISP = OLD 

At least 80 contiguous tracks must be available for work space on the volume defined 
by the SYSUTl DD statement. (This figure is based on a 2311 being the work volume. 
If a direct access device other than a 2311 is used, an equivalent amount of space 
must be available.) 

I When POWER = 2 is specified in the PARM field of the EXEC parameter, the number of 
contiguous tracks that must be available for work space on the volume is doubled; see 
"PARM Information on the EXEC Statement" below. 

The anynamel DD statement can be coded: 

//anynamel DD UNIT = xxxx,VOLUME = SER = xxxxxx.DISP = OLD 

In the anynamel DD statement, the UNIT and VOLUME parameters define the device 
type and volume serial number. The DiSP = OLD specification prevents the 
inadvertent deletion of a data set. The anynamel DD statement is arbitrarily assigned 
the ddname DDl in the lEHMOVE examples. 

The anyname2 DD statement can be coded: 

//anyname2 DD UNIT = xxxx, VOLUME = SER = xxxxxx,DISP = OLD 

When the number of volumes to be processed is greater than the number of devices 
defined by DD statements, there must be an indication (in the applicable DD 
statements) that multiple volumes are to be processed. This indication can be in the 
form of deferred mounting, as follows: 

//anyname2 DD UNIT = (xxxx,, DEFER), VOLUME = (PRIVATE,...), 
// DISP =(..., KEEP) 

See "Appendix C: DD Statements for Defining Mountable Devices" for information on 
defining mountable devices. The anyname2 DD statement is arbitrarily assigned the 
ddname DD2 in the lEHMOVE examples. DD statements defining additional mountable 
device types are assigned names DD3, DD4, etc. 
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Restrictions 



FARM Information on 
the EXEC Statement 



The tape DD statement can be coded: 

//tape DD DSNAME = xxxxxxxx,UNIT = xxxx, VOLUME = SER = xxxxxx, 

// DISP = (...,KEEP),LABEL = ( ),DCB = (TRTCH = C.DEN = x) 

when 7-track tape is to be used. A utility control statement parameter refers to the 
tape DD statement for label and mode information. 

The date on which a data set is moved or copied onto a magnetic tape volume is 
automatically recorded in the HDR 1 record of a standard tape label if a TODD 
parameter is specified in a utility control statement. An expiration date can be 
specified by including the EXPDT or RETPD subparameters of the LABEL keyword in 
the DD statement referred to by a TODD parameter. 

To define a sequence number for a data set on a tape volume, or to specify a specific 
device (for example, unit address 190), you must use a utility control statement 
instead of a DD statement. To move or copy a data set from or to a tape volume 
containing more than one data set, specify the sequence number of the data set in a 
utility control statement. To move or copy a data set from or to a specific device, 
specify the unit address (rather than a group name or device type) in a utility control 
statement. To copy to a unit record or unlabeled tape volume, specify any standard 
name or number in a utility control statement. 

The tape DD statement can be used to communicate DCB attributes of data sets 
residing on tape volumes that do not have standard labels to lEHMOVE. If no DCB 
attributes are specified, an undefined record format and a block size of 2560 are 
assumed. However, in order to recognize unloaded data sets on an unlabeled tape 
volume, the DCB attributes must be specified as follows: 
DCB = (RECFM = FB,LRECL = 80,BLKSIZE = 800). 

With the exception of the SYSIN and SYSPRINT DD statements, all DD statements 
shown in Table 51 are used as device allocation statements, rather than as true data 
definition statements. Because lEHMOVE modifies the internal control blocks created 
by device allocation DD statements, these statements must not include the DSNAME 
parameter. (All data sets are defined explicitly or implicitly by utility control 
statements.) 

A merge operation requires that one DD statement defining a mountable device be 
present for each source volume containing data to be included in the merge operation. 

Prior space allocations can be made by specifying a dummy execution of lEHPROGM 
before the execution of lEHMOVE. 

Blocked format data sets that do not contain user data TTRNs or keys can be 
reblocked or unblocked by including the proper keyword subparameters in the DCB 
operand of the DD statement used to previously allocate space for the data set. The 
new blocking factor must be a multiple of the logical record length originally assigned 
to the data set. (For a discussion of user data TTRNs, refer to OS Data Management 
Services Guide, GC26-3746.) 

• The block size for the SYSPRINT data set must be a multiple of 121. The block size 
for the SYSIN data set must be a multiple of 80. Any blocking factor can be 
specified for these block sizes. 

• One anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. 

• One anyname2 DD statement must be included for each mountable device to be 
used in the job step. 

• When lEHMOVE is dynamically invoked in a job step containing another program, 
the DD statements defining mountable devices for lEHMOVE must be included in 
the job stream prior to DD statements defining data sets required by the other 
program. 

The EXEC statement for lEHMOVE can contain PARM information that is used by 
the program to allocate additional work space and/or control line density on output 
listings. The EXEC statement can be coded, as follows: 



// EXEC PGM = IEHMOVE[,PARM = 



{ 'POWER = n' } 

{ 'POWER = n,LINECNT = XX' } 
{'LINECNT = xx' } 



The POWER = n parameter is used to request that the normal amount of space 
allocated for work areas be increased n times. lEHMOVE automatically calculates and 
allocates the amount of space needed for the work areas. No SPACE parameter, 
therefore, should be coded in the SYSUTl DD statement. If, in the EXEC statement. 
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Job Control Language for 
the Track Overflow Feature 



Utility Control Statements 



POWER = 3 is specified, the work space requirement is three times the basic 
requirements, etc. 

The POWER parameter is used when 750 or more members are being moved or 
copied. The progression for the value of n is: 

• POWER = 2 when 750 to 1,500 members are to be moved or copied. 

• POWER = 3 when 1,501 to 2,250 members are to be moved or copied. 

• POWER = 4 when 2,251 to 3,000 members are to be moved or copied. 

If POWER = 2, the work space requirement on the SYSUTl volume is two times the 
basic requirement; if POWER = 3, work space requirement is three times the basic 
requirement, etc. For example, if POWER = 2, 80 tracks on a 2314 must be available. 

When moving or copying a catalog, the value of the POWER parameter can be 
calculated, as follows: 

POWER = (lOD + V + 20G)/4000 

where D is the total number of data sets, aliases, and generation data set entries 
(which is the number of data set names printed by lEHLIST when LISTCTLG is 
specified); V is the total number of volumes used by these data sets (which is the 
number of lines printed by lEHLIST when LISTCTLG is specified); and G is the number 
of generated data sets. The progression of the value of n when moving or copying a 
catalog is: 

• POWER = 2 when 350 to 700 data sets reside on the catalog. 

• POWER = 3 when 701 to 1050 data sets reside on the catalog. 

• POWER = 4 when 1051 to 1400 data sets reside on the catalog. 

The LINECNT = xx parameter specifies the number of lines per page in the listing of 
the SYSPRINT data set; xx is a two-digit number in the range 04 through 99. 

A data set containing track overflow records can be moved or copied if the source 
volume and the receiving volume are mounted on direct access devices that support 
the track overflow feature. (For BDAM data sets, the source and receiving devices 
must be the same device type.) 

A data set that was written without track overflow can be moved or copied with or 
without track overflow or vice versa if the following conditions are met: 

• Space was allocated for the data set prior to the request for a move or copy 
operation. 

• The DD statement used for that allocation included the subparameter to specify the 
changed track overflow value and all other desired values. (The RECFM 
specifications assigned when the data set was originally created are overridden by 
the RECFM subparameter in this DD statement.) 

If space has not been allocated, or if RECFM was not specified when space was 
allocated, the data set is moved or copied in accordance with RECFM specifications 
that were made when the data set was originally created. 

The track overflow attribute is not retained for a sequential data set that is moved or 
copied to a device other than a direct access device. 

lEHMOVE is controlled by the following utility control statements: 

MOVE DSNAME statement, which is used to move a data set. 

COPY DSNAME statement, which is used to copy a data set. 

MOVE DSGROUP statement, which is used to move a group of cataloged data sets. 

COPY DSGROUP statement, which is used to copy a group of cataloged data sets. 

MOVE PDS statement, which is used to move a partitioned data set. 

COPY PDS statement, which is used to copy a partitioned data set. 

MOVE CATALOG, which is used to move cataloged entries. 

COPY CATALOG statement, which is used to copy cataloged entries. 

MOVE VOLUME statement, which is used to move a volume of data sets. 

COPY VOLUME statement, which is used to copy a volume of data sets. 
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MO\fE DSNAME Statement 



In addition, there are four sutxrdinate control statements that can be used to modify 
the effect of a MOVE DSGROUP, COPY DSGROUP, MOVE PDS, COPY PDS, MOVE 
CATALOG, or COPY CATALOG operation. The subordinate control statements are: 

• INCLUDE statement, which is used to enlarge the scope of a MOVE DSGROUP, 
COPY DSGROUP, MOVE PDS, or COPY PDS statement by including a member or 
data set not explicitly included by the statement it modifies. 

• EXCLUDE statement, which is used with a MOVE DSGROUP, COPY DSGROUP, 
MOVE PDS, COPY PDS, MOVE CATALOG, or COPY CATALOG statement to exclude 
data from the move or copy operation. 

• REPLACE statement, which is used with a MOVE PDS or COPY PDS statement to 
exclude a member from a move or copy operation and to replace it with a member 
from another partitioned data set. 

• SELECT statement, which is used with MOVE PDS or COPY PDS statements to 
select members to be moved or copied and, optionally, to rename the specified 
members. 

The MOVE DSNAME statement is used to move a data set. The source data set is 
scratched. 

The format of the MOVE DSNAME statement is: 

[label] MOVE DSNAME = name 
,T0 = device = list 
[JROM = device = list ] 
[,CVOL = device = seriaf] 
[.UNCATLG] 
[.RENAME = name] 
[.FROMDD = ofdname] 
[,TODD = ddname] 
[.UNLOAD] 
where: 

DSNAME = name 

specifies the fully-qualified name of the data set to be moved. 

TO = device = list 

specifies the volume or volumes to which the data set is to be moved. 

FROM = device = list 

specifies the volume or volumes on which the data set currently resides, if it is not 
cataloged. If the data set is cataloged, FROM need not be written. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If neither CVOL nor FROM is written, the 
data set is assumed to be cataloged on the system residence volume. 

UNCATLG 

specifies that the catalog entry pertaining to the data set is to be removed. This 
parameter should be used only if the source data set is cataloged. UNCATLG is 
ignored if the volume is identified by FROM. 

RENAME = name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter is valid for data sets residing on magnetic tape volumes. 
See Table 51 and the tape DD statement under "Job Control Statements" for 
additional information. 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter, which is valid for data sets to be moved to tape volumes, 
describes the mode and label of the volume where the moved data set is to reside. 
RECFM, LRECL, and BLKSIZE information is ignored. 

UNLOAD 

specifies that the data set is to be unloaded to the receiving volume(s). 

If the data set is cataloged, the catalog is automatically updated unless UNCATLG is 
specified. 
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copy DSNAME Statement 



MOVE DSGROUP Statement 



The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tape with standard labels on single-density drives or for 1600 bits per inch, 9-track 
tape with standard labels on dual-density drives. 

The COPY DSNAME statement is used to copy a data set. 

The format of the COPY DSNAME statement is: 

^^___,_„_ 

■,';.,;' JO -device — list 

■ [,FRpM, »»=;clev/ce:.«» /ist ■v:l; ■'::'.■,: 
' '■yi,cy 01 =« device"'^ serial]':}''' ■^■>^ 

■■"^>-''^:\'*;^;')^-rirf^'f '(.RENAME'-^ 

'}y}0M}}}Mi--<lJ^ 

e,mnMd] '"■'■"■ 

where: 

DSNAME = name 

specifies the fully-qualified name of the data set to be copied. 

TO = device — list 

specifies the volume or volumes on which the data set is to be copied. 

FROM = device = list 

specifies the volume or volumes on which the data set currently resides, if it is not 
cataloged. If the data set is cataloged, FROM should not be written. 

CVOL = device = setial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If neither CVOL nor FROM is written, the 
data set is assumed to be cataloged on the system residence volume. 

UNCATLG 

specifies that the catalog entry pertaining to the source data set is to be removed. 
This parameter may only be used if the source data set is cataloged. UNCATLG is 
ignored if the volume is identified by FROM. 

CATLG 

specifies that the copied data set is to be cataloged on its receiving volume if it is a 
direct access volume. If a catalog does not exist on the receiving volume, a new 
catalog is created. 

RENAME = name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD = ddname 

specifies the name of the DD statement from which DCB and LABEL information are 
obtained. DCB attributes for unloaded data sets are always RECFM = FB, 
LRECL = 80, and BLKSIZE = 800. This parameter is valid for data sets residing on 
tape volumes. See Table 51 and the tape DD statement under "Job Control 
Statements" for additional information. 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are ■ 
obtained. This parameter, which is valid for data sets to be copies onto magnetic I 
tape volumes, describes the mode and label of the magnetic tape where the copied 
data set is to reside. RECFM, LRECL, and BLKSIZE information is ignored. 

UNLOAD 

specifies that the data set is to be unloaded to the receiving volume(s). 

Note: The source data set, if cataloged, remains cataloged unless UNCATLG is 
specified. 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tape with standard labels on single-density drives or for 1600 bits per inch, 9-track 
tape with standard labels on dual-density drives. 

The MOVE DSGROUP statement is used to move groups of data sets that are 
cataloged on the same volume and whose names are partially qualified by one or more 
identical names. Source data sets are scratched. Data set groups to be moved must 
reside on direct access volumes. 
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INCLUDE and EXCLUDE statements, discussed later in this chapter, can be used to 
add to or delete data sets from the group. 

The format of the MOVE DSGROUP statement Is: 
,T0 = device = list 



[,CVOL s= device = 
[,PASSWORD] 
[.UNCATLG] 
[,TODD =« ddname] 
[.UNLOAD] 



serial] 



where: 

DSGROUP [ = name] 

specifies the cataloged data sets to be moved. If name, which is a qualified name, is 
not coded, all data sets cataloged on the specified volume are to be moved. If 
name is coded, all cataloged data sets whose names are qualified by this name are 
moved. If the name is a fully-qualified data set name, only that data set is moved. 

TO = device = list 

specifies the volume or volumes to which the specified group of data sets is to be 
moved. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the data sets is to begin. If CVOL is omitted, the specified group 
of data sets is assumed to be cataloged on the system residence volume. 

PASSWORD 

specifies that password -protected data sets contained in the group are to be 
moved. If PASSWORD is omitted, only data sets that are not protected are moved. 

UNCATLG 

specifies that the catalog entries pertaining to the specified group of data sets are 
to be removed. 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter, which is valid for data set groups to be moved to 
magnetic tape volumes, describes the mode and label of the magnetic tape where 
the moved data sets are to reside. RECFM, LRECL, and BLKSIZE information is 
ignored. TODD can be omitted for 800 bits per inch, 9-track tape with standard 
labels on single-density drives or for 1600 bits per inch, 9-track tape with standard 
labels on dual-density drives. 

UNLOAD 

specifies that the data set is to be unloaded to the receiving volume(s). 

MOVE DSGROUP operations cause the specified catalog to be updated automatically 
unless UNCATLG is specified. 

The COPY DSGROUP statement is used to copy groups of data sets that are cataloged 
on the same control volume and whose names are partially qualified by one or more 
identical names. Data set groups to be copied must reside on direct access volumes. 

INCLUDE and EXCLUDE statements, discussed later in this chapter, can be used to 
add data sets to or delete data sets from the data set group to be copied. 

The format of the COPY DSGROUP statement is: 

[/abe/] COPY DSGROUP[ = name] 
,T0 = device = list 
[,CVOL = device = serial] 
[.PASSWORD] 
[.UNCATLG] 
[.CATLG] 

[,TODD = ddname] 
[.UNLOAD] 
where: 

DSGROUP[ = name] 

specifies the cataloged data sets to be copied. If name, which is a qualified name, is 
not coded, all cataloged data sets on the specified volume are to be copied. If 
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name is coded, all cataloged data sets whose names are qualified by this name are 
copied. If the name is a fully-qualified data set name, only that data set is copied. 

TO = device = list 

specifies the volume or volumes on which the specified group of data sets is to be 
copied. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
search for the catalog is to begin. If CVOL is omitted, the specified group of data 
sets is assumed to be cataloged on the system residence volume. 

PASSWORD 

specifies that password-protected data sets contained in the group are to be 
copied. If PASSWORD is omitted, only data sets that are not protected are copied. 

UNCATLG 

specifies that the catalog entries pertaining to the source group of data sets are to 
be removed. 

CATLG 

specifies that the copied data sets are to be cataloged on their receiving volumes if 
they are direct access volumes. If catalogs do not exist on the receiving volumes, 
they are created. 

TODD = ddname 

specifies the name of a DO statement from which DCB and LABEL information are 
obtained. This parameter, which is valid for data set groups to be copied to 
magnetic tape volumes, describes the mode and label of the magnetic tape on 
which the copied data sets are to reside. RECFM, LRECL, and BLKSIZE information 
is ignored. TODD can be omitted for 800 bits per inch, 9-track tapes with standard 
labels on single-density drives or for 1600 bits per inch, 9-track tape with standard 
labels on dual-density drives. 

UNLOAD 

specifies that the data set is to be unloaded to the receiving volume(s). 

Note: The source data sets remain cataloged unless UNCATLG is specified. 

MOVE PDS Statement The MOVE PDS statement is used to move partitioned data sets. When used in 

conjunction with INCLUDE, EXCLUDE, REPLACE, or SELECT statements, the MOVE 
PDS statement can be used to merge selected members of several partitioned data 
sets or to delete members. 

If lEHMOVE is used to allocate space for an output partitioned data set, the MOVE 
PDS statement can be used to expand a partitioned directory. 

If the receiving volume contains a partitioned data set with the same name, the two 
data sets are merged. The source data set is scratched if its expiration date has 
occurred. 

The format of the MOVE PDS statement is: 

■ [label] MOVE PDS = name 

,T0 = device = serial 

[,FROM = device = serial] 
: [,CVOL == device = serial] 

[.EXPAND = nn] 
i [.UNCATLG] 

: [.RENAME = name] ': 

[.FROMDD = ddname] 

[,TODD = ddname] 

where:""'""""'"""""* " .-...-.-—.. -.,. ,^..^ ..„,..„.„,. .„„.„.,.„„.„„.„...„.„_,._.„„., ......... 

PDS = name 

specifies the fully-qualified name of the partitioned data set to be moved. 

TO = device = serial 

specifies the device type and volume serial number of the volume to which the 
partitioned data set is to be moved. The list parameter may be used when 
unloading a partitioned data set that must span tape volumes. 
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FROM = cfeWce = serial 

specifies the device type and volume serial number of the volume on which the 
partitioned data set currently resides, if it is not cataloged. If the data set is 
cataloged, FROM need not be written. FROM = device = list may be used when 
loading a PDS. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the partitioned data set is to begin. If neither FROM nor CVOL is 
written, the partitioned data set is assumed to be cataloged on the system 
residence volume. 

EXPAND = nn 

specifies the number of 256-byte records (up to 99 decimal) to be added to the 
directory of the specified partitioned data set. EXPAND cannot be specified if space 
is previously allocated. 

UNCATLG 

specifies that the catalog entry pertaining to the source partitioned data set is to 
be removed. This parameter may only be used if the source data set is cataloged. If 
the volume is identified by FROM, UNCATLG is ignored. 

RENAME = r)ame 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD = ddname 

specifies the name of a DD statement from which DOB and LABEL information are 
obtained. This parameter, which is valid for unloaded partitioned data sets on tape 
volumes, describes the mode and label of the magnetic tape and, in addition, must 
Include the DOB attributes of the unloaded data set (RECFM = FB.LRECL = 80, 
BLKSIZE = 800). See Table 51 and the tape DD statement under "Job Control 
Statements" for additional information. 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter, which is valid for partitioned data sets to be unloaded to 
tape volumes, describes the mode and label of the magnetic tape on which the 
unloaded data set is to reside and, in addition, must include the DCB attributes of 
the unloaded data set (RECFM = FB,LRECL = 80,BLKSIZE = 800). 

FROMDD can be omitted for 800 bits per inch, 9-track tapes with standard labels on 
single-density drives or for 1600 bits per inch, 9-track tape with standard labels on 
dual-density drives. 

Note: MOVE PDS causes the specified catalog to be updated automatically unless 
UNCATLG is specified. 

The COPY PDS statement is used to copy partitioned data sets. When used in 
conjunction with INCLUDE, EXCLUDE, REPLACE, or SELECT statements, the COPY 
PDS statement can be used to merge selected members of several partitioned data 
sets or to delete members. 

If lEHMOVE is used to allocate space for an output partitioned data set, the COPY PDS 
statement can be used to expand a partitioned directory. 

If the receiving volume already contains a partitioned data set with the same name, 
the two are merged. 

The format of the COPY PDS statement is: 

[label] COPY PDS = name 

,T0 = device = serial 

[,FROM = device = serial] 

[,CVOL = deWce = serial] 

[,EXPAND = nn] 

[.UNCATLG] 

[.CATLG] 

[.RENAME = name] 

[.FROMDD = ddname] 

[.TODD = ddname] 
where: 

PDS = name 

specifies the fully-qualified name of the partitioned data set to be copied. 
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MOVE CATALOG Statement 



TO = device = serial 

specifies the device type and volume serial number of the volume to which the 
partitioned data set is to be moved. The list value may be used when unloading a 
partitioned data set that must span tape volumes. 

FROM = device = serial 

specifies the device type and volume serial number of the volume on which the 
partitioned data set currently resides, if it is not cataloged. If the data set is 
cataloged, FROM need not be written. FROM = device = list may be used when 
loading a PDS. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the partitioned data set is to begin. If neither FROM nor CVOL is 
written, the partitioned data set is assumed to be cataloged on the system 
residence volume. 

EXPAND = nn 

specifies the number of 256-byte records (up to 99 decimal) to be added to the 
directory of the specified partitioned data set. EXPAND cannot be specified if space 
is previously allocated. 

UNCATLG 

specifies that the catalog entry pertaining to the source partitioned data set is to 
be removed. This parameter should be used only if the source partitioned data set 
is cataloged. UNCATLG is ignored if the volume is identified by FROM. 

CATLG 

specifies that the copied partitioned data set is to be cataloged on the receiving 
volume if it is a direct access volume. If a catalog does not exist on the receiving 
volume, a new catalog is created. 

RENAME = name 

specifies that the data set is to be renamed, and indicates the new name. 

FROMDD = ddname 

specifies the name of a DD statement from which DOB and LABEL information are 
obtained. This parameter, which is valid for unloaded partitioned data sets residing 
on magnetic tape volumes, describes the mode and label of the magnetic tape and, 
in addition, must include the DCB attributes of the unloaded data set (RECFM = FB, 
LRECL = 80,BLKSIZE = 800). See Table 51 and the tape DD statement under "Job 
Control Statements" for additional information. 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter, which is valid for partitioned data sets to be unloaded to 
magnetic tape volumes, describes the mode and label of the magnetic tape on 
which the unloaded data set is to reside and, in addition, must include the DCB 
attributes of the unloaded data set (RECFM = FB,LRECL = 80,BLKSIZE = 800). 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single-density drives or for 1600 bits per inch, 9-track 
tape with standard labels on dual-density drives. 

Note: The source partitioned data set remains cataloged unless UNCATLG is specified. 

The MOVE CATALOG statement is used to move the entries of a catalog without 
moving the data sets associated with those entries. Certain entries can be excluded 
from the operation by means of the EXCLUDE statement. If the receiving volume 
contains a catalog, the source catalog entries are merged with it. 

The format of the MOVE CATALOG statement is: 



ilabel] MOVE 



CATALOG [ = name] 
,T0 = device = serial 
[,CVOL = device = seriaf] 
[,FROM = device = serial} 
[.FROMDD « ddname] 
[,TODD = ddname] 
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where: 

CATALOG [ = name] 

specifies the catalog entries to be moved. If name, which is a fully-qualified name, 
is not coded, all entries in the catalog are to be moved, if name is coded, all catalog 
entries whose names are qualified by this name are moved. If the name is a 
fully-qualified data set name, only the catalog entry that corresponds to that data 
set is moved. 

TO = device = serial 

specifies the device type and volume serial number of the volume to which the 
specified catalog entries are to be moved. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
search for the catalog is to begin, if both FROM and CVOL are omitted, the catalog 
is assumed to reside on the system residence volume. 

FROM = device = serial 

specifies the device type and volume serial number of the volume on which an 
unloaded version of the catalog resides. If neither FROM nor CVOL is coded, the 
catalog is assumed to reside on the system residence volume. 

FROMDD = ddname 

specifies the name of a DO statement from which DOB and LABEL information are 
obtained. This parameter, which is valid for unloaded catalogs residing on magnetic 
tape volumes, describes the mode the label of the magnetic tape and, in addition, 
must include the DCB attributes of the unloaded catalog (RECFM = FB,LRECL = 80, 
BLKSIZE = 800). See Table 51 and the tape DD statement under "Job Control 
Statements" for additional information, 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter, which is valid for catalogs to be unloaded to magnetic 
tape volumes, describes the mode and label of the magnetic tape on which the 
unloaded catalog is to reside. 

The FROMDD and TODD parameters can be omitted for 800 bits per inch, 9-track 
tapes with standard labels on single-density drives or for 1600 bits per inch, 9-track 
tape with standard labels on dual-density drives. 

The COPY CATALOG statement is used to copy the entries in a catalog without 
copying the data sets associated with these entries. Certain entries can be excluded 
from a copy operation with the EXCLUDE statement. If the receiving volume contains a 
catalog, the source catalog is merged with it. 

The format of the COPY CATALOG statement is: 



[label] COPY 



CATALOG [ = r)ame] 
,T0 = device = serial 
[,CVOL = device = serial] 
[.FROM = device = serial] 
[.FROMDD = ddname] 
[.TODD = ddname] 



where: 



CATALOG [ = name] 

specifies the catalog entries to be copied. If name, which is a fully-qualified name, 
is not coded, all entries in the catalog are to be copied. If name is coded, all catalog 
entries whose names are qualified by this name are copied. If the name is a 
fully-qualified data set name, only the catalog entry that corresponds to that data 
set is copied. 

TO = device = serial 

specifies the device type and volume serial number of the volume onto which the 
specified catalog entries are to be copied. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
search for the catalog is to begin. 

FROM = dewce = serial 

specifies the device type and volume serial number of the volume on which an 
unloaded version of the catalog resides. If neither FROM nor CVOL is written, the 
catalog is assumed to reside on the system residence volume. 
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COPY VOLUME Statement 



FROMDD = ddname 

specifies the name of a DD statement from which DCB and LABEL Information is 
obtained. This parameter, which is valid for unloaded catalogs residing on tape 
volumes, describes the mode and label of the tape and, in addition, must Include 
the DCB attributes of the unloaded catalog (RECFM => FB,LRECL = 80, 
BLKSIZE = 800). See Table 51 and the tape DD statement under "Job Control 
Statements" for additional information. 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter, which Is valid for catalogs to be unloaded onto tape 
volumes, describes the mode and label of the tape volume on which the unloaded 
catalog is to reside. 

The FROMDD and TODD parameters can be omitted for 800 bits per Inch, 9-track 
tapes with standard labels on single-density drives or for 1600 bits per inch, 9-track 
tape with standard labels on dual-density drives. 

The MOVE VOLUME statement Is used to move all the data sets residing on a specified 
volume. Catalog entries associated with the data sets remain unchanged. Data sets to 
be moved must reside on direct access volumes. 

The format of the MOVE VOLUME statement is: 

,T0'=';c>ev/ce:»^^7/stv;"'?^ 

[.PASSVVpRDJ^^^^^^^^^ 

l^Of>P:==^^d<ir\airn^ 

[ilgllll''^"'''''''^'''''''''^''''"'''"'^'^ 

where: 



VOLUME = device = serial 

specifies the device type and volume serial number of the source volume. 

TO = device — list 

specifies the volume or volumes to which the data sets are to be moved. 

PASSWORD 

specifies that password- protected data sets are to be included in the operation. If 
PASSWORD is omitted, only data sets that are not protected are moved. 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter, which is valid for data sets to be moved to tape volumes, 
describes the mode and label of the receiving tape volume. If the RECFM, BLKSIZE, 
and LRECL parameters were specified, they are ignored. TODD can be omitted for 
800 bits per Inch, 9-track tapes with standard labels on single-density drives or for 
1600 bits per inch, 9-track tape with standard labels on dual-density drives. 

UNLOAD 

specifies that the data set is to be unloaded to the receiving volume(s). 

The COPY VOLUME statement is used to copy all the data sets residing on a specified 
volume. Catalog entries associated with the data sets remain unchanged. Data sets to 
be copied must reside on direct access volumes. 

The format of the COPY VOLUME statement is: 

T'l/ateOCOPy' VOLUME~=dew^^ -"""—"- 1 

; JO »« device <=llst j 

I [.PASSWORD] j 

j LCATLG] ., ■ j 

; [,TODD = cfdname] \ 

I [.UNLOAD] 1 



where: 

VOLUME = deWce = serial 

specifies the device type and volume serial number of the source volume. 

TO = device = list 

specifies the volume or volumes to which the data sets are to be copied. 
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PASSWORD 

specifies tliat password -protected data sets are to be included in tiie operation. If 
PASSWORD is omitted, only data sets that are not protected are copied. 

CATLG 

specifies that all copied data sets are to be cataloged in a SYSCTLG (system 
catalog) data set on the direct access receiving volume. If a catalog does not exist 
on the receiving volume, it is created. 

TODD = ddname 

specifies the name of a DD statement from which DCB and LABEL information are 
obtained. This parameter, which is valid for data sets to be copied to magnetic tape 
volumes, describes the mode and label of the receiving magnetic tape volume. If 
RECFM, BLKSIZE, and LRECL were specified, they are ignored. TODD can be 
omitted for 800 bits per inch, 9-track tapes with standard labels on single-density 
drives or for 1600 bits per inch, 9-track tape with standard labels on dual-density 
drives. 

UNLOAD 

specifies that the data set is to be unloaded to the receiving volume(s). 

If CATLG is specified and the source volume contains a SYSCTLG data set, error 
messages indicating that an inconsistent index structure exists are issued when the 
source SYSCTLG data set entries are merged into the catalog on the receiving volume. 
(Because the SYSCTLG data set is the last to be copied, only those entries 
representing cataloged data sets not residing on the source volume are copied into a 
receiving volume's SYSCTLG data set; entries representing all data sets residing on 
the source volume have already been made in the receiving SYSCTLG data set.) 

The INCLUDE statement is used to enlarge the scope of MOVE DSGROUP, COPY 
DSGROUP, MOVE PDS, or COPY PDS statements by including a member or a data set 
not explicitly defined in those statements. The INCLUDE statement follows the MOVE 
or COPY statement whose function it modifies. Any number of INCLUDE statements 
can modify a MOVE or COPY statement. The INCLUDE statement is invalid when data 
is unloaded or when unloaded data is moved or copied. 

The format of the INCLUDE statement is: 

[label] INCLUDE DSNAME = name 

[,MEMBER = membername] 
[.FROM = device = list ] 
[,CVOL = device = serial] 
where: 

DSNAME = name 

specifies the fully-qualified name of a data set. When the INCLUDE statement 
modifies a MOVE DSGROUP or COPY DSGROUP statement, the named data set is 
included in the group. When the INCLUDE statement modifies a MOVE PDS or 
COPY PDS statement, either the entire named partitioned data set or a member of 
the data set is included in the operation. 

MEMBER = membername 

specifies the name of a member of the partitioned data set named in the DSNAME 
parameter. This member is merged with the partitioned data set that is moved or 
copied. Its record characteristics must be the same as those of the data set with 
which it it being merged. The data set containing this member is not scratched, 
regardless of the operation. This parameter is valid and required only when the 
INCLUDE statement modifies a MOVE PDS or COPY PDS statement. 

FROM = device = list 

specifies the volume or volumes on which the data set resides, if the data set is not 
cataloged. If the data set is cataloged, FROM need not be specified. If both FROM 
and CVOL are omitted, the specified data set is assumed to be cataloged on the 
system residence volume. 



EXCLUDE Statement 



CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If both FROM and CVOL are omitted, the 
specified data set is assumed to be cataloged on the system residence volume. 

The EXCLUDE statement is used to restrict the scope of MOVE DSGROUP, COPY 
DSGROUP, MOVE PDS, COPY PDS, MOVE CATALOG, or COPY CATALOG statements 
by excluding a specific portion of data defined in those statements. 
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REPLACE Statement 



Partitioned data set members excluded from a IVIOVE PDS operation cannot be 
recovered (the source data set is scratched). Any number of EXCLUDE statements can 
modify a MOVE PDS or COPY PDS statement. 

Source data sets or catalog entries excluded from a MOVE DSGROUP or MOVE 
CATALOG operation remain available. Only one EXCLUDE statement can modify a 
MOVE DSGROUP, COPY DSGROUP, MOVE CATALOG, or COPY CATALOG statement. 
The EXCLUDE statement is invalid when data is unloaded or when unloaded data is 
moved or copied. 

The format of the EXCLUDE statement is: 



[label] EXCLUDE 



(DSGROUP = name } 

(MEMBER = membername } 



where: 



DSGROUP = name 

specifies a qualified name. If the EXCLUDE statement modifies a MOVE DSGROUP 
or COPY DSGROUP statement, all data sets whose names are qualified by this 
name are excluded from the operation. If the EXCLUDE statement modifies a 
MOVE CATALOG or COPY CATALOG statement, all catalog entries whose names 
are qualified by this name are excluded from the operation. 

MEMBER = membername 

identifies a member to be excluded from the partitioned data set being moved or 
copied when the EXCLUDE statement modifies a MOVE PDS or COPY PDS 
statement. 

The SELECT statement is used with the MOVE PDS or COPY PDS statement to select 
members to be moved or copied, and to optionally rename these members. The 
SELECT statement cannot be used with either the EXCLUDE or REPLACE statement to 
modify the same MOVE PDS or COPY PDS statement. The SELECT statement is invalid 
when data is unloaded or when unloaded data is moved or copied. 

The format of the SELECT statement is: 



[labefl SELECT 



(MEMBER = (name[,name...) } 

( MEMBER = {{name,newname)[,(name,newname)]. . .) } 



where: 



MEMBER = (name[,name]...) 

identifies the members to be moved or copied. These members belong to the 
partitioned data set identified in the preceding MOVE PDS or COPY PDS statement. 

MEMBER = ((name,newname(„(name,newname)]...) 

identifies the members to be moved or copied and gives the new name for each 
member. 

The REPLACE statement is used with a MOVE PDS or COPY PDS statement to exclude 
a member from the operation and replace it with a member from another partitioned 
data set. The new member must have the same name as the old member and must 
possess identical record characteristics. Any number of REPLACE statements can 
modify a MOVE PDS or COPY PDS statement. The REPLACE statement is invalid when 
data is unloaded or when unloaded data is moved or copied. 

The format of the REPLACE statement is: 

[label] REPLACE DSNAME = name 
, MEMBER = name 

[,FROM = deWce = serial] 
[,CVOL = dewce = serial] 

where: 

DSNAME = name 

specifies the fully-qualified name of the partitioned data set that contains the new 
member. 

MEMBER = name 

specifies the name of the member. 

FROM = device = serial 

specifies the device type and volume serial number of the volume that contains the 
partitioned data set named in the DSNAME parameter. If the partitioned data set is 
cataloged, FROM need not be specified. 
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CVOL = device = serial 

specifies the device type and volume serial number of the control volume on which 
the catalog search for the partitioned data set containing the new member is to 
begin. 

If neither FROM nor CVOL is specified, the partitioned data set is assumed to be 
cataloged on the system residence volume. 

The following examples illustrate some of the uses of lEHMOVE. Table 52 can be used 
as a quick reference guide to lEHMOVE examples. The numbers in the "Example" 
column point to the examples that follow. 

Table 52. lEHMOVE Example Directory 



Operation 

MOVE 



Data Set 
Organization 

Sequential 



Device 

3330 Disk, 
2314 Disks 



COPY 



MOVE 



Sequential 2314 Disk, 

3330 Disk, 
2314 or 
2319 Disks! 

Data set group 2311 Disk, 
2301 Drum, 
2314 Disk 



MOVE PDS Partitioned 



MOVE and 
CATALOG 



MOVE 



MOVE 



MOVE 



MOVE 



MOVE 



MOVE 



COPY 



COPY 



Catalog 



Catalog 



Volume 



Partitioned 



Partitioned 



Sequential 



Sequential 



Sequential 



Partitioned 



3330 Disk, 
2311 Disk 
2314 Disks 

2314 Disk, 
3330 Disk, 
2311 Disk 

3330 Disk, 
2314 Disk 



3330 Disk, 
2314 Disks 

2301 Drum, 
2314 Disks 

3330 Disk, 
2311 Disk, 
2314 Disk 

2311 Disk, 
2314 Disk, 
2400 Tape 

3330 Disk, 
2314 Disk, 
2400 Tape 

2314 Disk, 
2311 Disk, 
2400 Tape 

2400 Tape, 
2314 Disks 



Comments 

Source volume is demounted after 
job completion. Two mountable 
disks. 

Three cataloged sequential data 
sets are to be copied. The 2314 
or 2319 are mountable. 

Data set group is to be moved. The 
2314 disks are mountable. 

A partitioned data set is to be 
moved; a member from another 
PDS is to be merged with it. 

Catalog is to be moved from 
system residence volume to second 
volume. Source catalog is scratched 
from system residence volume. 

Selected catalog entries are to be 
moved from system residence to 
a second volume. SYSCTLG is 
scratched. 

Volume of data sets is to be moved. 

A data set is to be moved to a 
volume on which space was 
previously allocated. 

Three data sets are to be moved 
and unloaded to a volume on which 
space was previously allocated. 

A sequential data set is to be 
unloaded to an unlabeled 9-track 
tape volume. 

Unloaded data sets are to be 
loaded from a single volume. 

Data sets are to be copied from 
separate source volumes. 



Example 



10 



11 



12 



Unloaded data sets are to be 

loaded from unlabeled tape to a 

specific device. 13 

1 Note that the 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 2314 
in the control statement. 
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lEHMOVE Example 2 



In this example, three data sets (SEQSETl, SEQSET2, and SEQSET3) are to be moved 
from a disk volume to three separate disk volumes. Each of the three receiving 
volumes is mounted when it is required by lEHMOVE. The source data sets are not 
cataloged. Space is allocated by lEHMOVE. 

The example follows: 



//MOVEDS 

// 
//SYSPRINT DD 



//SYSUT1 

//DD1 

//DD2 



JOB 09#550, GREEN 

EXEC PGM=IEHMOVE 
SYSOUT=A 

UNIT=3330,VOLUME=SER=333000,DISP=OLD 
UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=( 2314,, DEFER ) , DISP=OLD , 



DD 
DD 
DD 



// VOLUME=( PRIVATE, , SER=( 23 1 400 ) ) 



//DD3 



// UNIT=2314,DISP=OLD 



DD VOLUME=( PRIVATE, RETAIN, SER=( 23141 1 )), 



//SYSIN DD 

MOVE 

MOVE 

MOVE 
/* 

The control statements are discussed below: 



DSNAME=SEQSET1 , TO=23 1 4=231 400 , FROM=23 1 4=231 41 1 
DSNAME=SEQSET2 , TO=23 1 4=23 1 412, FROM=23 1 4=23 1 4 1 1 
DSNAME=SEQSET3 , TO=23 1 4=23 1 413, FROM=23 1 4=23 1411 



• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines the mountable device on which the receiving volumes will be 
mounted as they are required. 

• DD3 DD defines a mountable device on which the source volume Is to be mounted. 
Because the RETAIN subparameter is included, the volume remains mounted until 
the job has completed. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE moves the source data sets to volumes 231400, 231412, and 231413, 
respectively. The source data sets are scratched. 

In this example, three cataloged data sets are to be copied to a 2314 or 2319 volume. 
Note that the 2319 is functionally equivalent to the 2314; to use a 2319, specify 
2314 in the control statement. Space is allocated by lEHMOVE. The catalog is not 
updated. The source data sets are not scratched. 

The example follows: 

09#550, GREEN 

PGM=IEHMOVE 

SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1400, DISP=OLD 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 40 1 , DISP=OLD 

* 

DSNAME=SEQSET1 , TO=231 4=23 1 40 1 

DSNAME=SEQSET3 , TO=23 1 4=23 1 40 1 

DSNAME=SEQSET4 , TO=23 1 4=23 1 40 1 
/* 
The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volume is mounted. 

• DD3 DD defines a mountable device on which the receiving volume is mounted. 

• SYSIN DD defines the control data set which follows in the input stream. 

• COPY copies the source data sets onto volume 231401. 

Note: This example implies that the cataloged source data sets all exist on a 2314 
volume. If the data sets existed on a volume or volumes other than a 2314, the 
necessary DD statements would have to be included in this example to define the 
applicable mountable device(s). 



//COPYPDS JOB 


// 


EXEC 


//SYSPRINT DD 


//SYSUTl 


DD 


//DDl 


DD 


//DD2 


DD 


//DD3 


DD 


//SYSIN 


DD 




COPY 




COPY 




COPY 
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lEHMOVE Example 4 



In this example, the data set group A.B.C — which comprises data sets A.B.C.X, 
A.B.C.Y, and A.B.C.Z — is moved from two 2314 volumes onto a third volume. Space is 
allocated by lEHMOVE. The catalog is updated to refer to the receiving volume. The 
source data sets are scratched. 

The example follows: 

//MOVEDSG 

// 
//SYSPRINT DD 

DD 

DD 

DD 

DD 

DD 

DD 
MOVE 



JOB 09#550, GREEN 

EXEC PGM=IEHMOVE 
SYSOUT=A 

UNIT=2311 ,VOLUME=SER=231 101 ,DISP=OLD 
UNIT=2301 , V0LUME=SER=1 11111 ,DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 401 , DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 410, DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1411, DISP=OLD 
* 

DSGROUP=A . B . C, T0=2 3 1 4=2 31401 



//SYSUT1 

//DD1 

//DD2 

//DD3 

//DD4 

//SYSIN 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the receiving volume is to be 
mounted. 

• DD3 DD defines a mountable device on which one of the source volumes is to be 
mounted. 

• DD4 DD defines a mountable device on which one of the source volumes is to be 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE moves the specified data sets to volume 231401. 

Note: This example can be used to produce the same result without the use of the 
DD4 DD statement, using one less mountable 2314 device. With DD3 and DD4, both 
of the source volumes are mounted at the start of the job. With DD3 only, the 231410 
volume is mounted at the start of the job. After the 231410 volume is processed, the 
utility requests that the operator mount the 231411 volume. In this case the DD3 
statement is coded: 

//DD3 DD UNIT = (23 14„DEFER),DISP = OLD.VOLUME = (PRIVATE,, 
// SEP = (231410)) 

In this example, a partitioned data set (PARTSETl) is to be moved to a disk volume. In 
addition, a member (PARMEM3) from another partitioned data set (PARTSET2) is to 
be merged with the source members on the receiving volume. The source partitioned 
data set (PARTSETl) is scratched. Space is allocated by lEHMOVE. 

The example follows: 



JOB 09#550, GREEN 
EXEC PGM=IEHMOVE 



//MOVEPDS 
// 

//SYSPRINT DD 
//SYSUTl DD 
//DDl DD 
//DD2 DD 
//DD3 DD 
//DD4 DD 
//SYSIN DD 
MOVE 
INCLUDE 
/* 

The control statements are discussed below: 



SYSOUT=A 

UNIT=3330,VOLUME=SER=333000,DISP=OLD 
UNIT=231 1 ,V0LUME=SER=1 11111 ,DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 410, DISP=OLD 
UNIT=2314,VOLUME=SER=231420,DISP=OLD 
* 

PDS=PARTSET1 , TO=231 4=231 420 , FROM=23 14=23 1400 
DSNAME=PARTSET2 , MEMBER=PARMEM3 , FROM=23 1 4=23 1 4 1 



• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• The DD2, DD3, and DD4 DD statements define mountable devices that are to 
contain the two source volumes and the receiving volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE defines the source partitioned data set, the volume that contains it, and its 
receiving volume. 

• INCLUDE includes a member from a second partitioned data set in the operation. 
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//SYSUT1 


DD 


//DD1 


DD 


//DD2 


DD 


//SYSIN 


DD 




MOVE 



In this example, the SYSCTLG data set is to be moved from the system residence 
volume to a mountable 2311 volume. Space is allocated by lEHMOVE. The source 
catalog is scratched from the system residence volume. 

The example follows: 

//M0VECAT1 JOB 09#550, GREEN 

// EXEC PGM= lEHMOVE 

//SYSPRINT DD SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=231 1 ,VOLUME=SER=222222,DISP=OLD 
* 

CATALOG, TO=231 1=222222 
/* 

The control statements are discussed below: 

o SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. The system residence volume 
contains the catalog to be moved. 

• DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies the move operation and defines the receiving volume. 

In this example, the data set group A.B.C — which comprises data sets entries A.B.C.X, 
A.B.C.Y, and A.B.C.Z — is to be moved from the SYSCTLG data set to a mountable 
2314 volume. If no catalog exists on the 2314 volume, one is created; if a catalog 
does exist, the specified entries are merged into it. The source SYSCTLG data set is 
scratched. The work data set is deleted when the job step is completed. 

The example follows: 

//M0VECAT2 JOB 09#550, GREEN 
// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 



//SYSUTl DD 
//DD 1 DD 
//DD2 DD 
//SYSIN DD 
MOVE 
/* 

The control statements are discussed below: 



UNIT=23 1 4 , VOLUME=SER=23 1 402 , DISP=OLD 
UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1 402 , DISP=OLD 
* 

CATALOG=A. B . C, TO=23 1 4=23 1 402 



• SYSUTl DD defines the device that is to contain the work data set. (Because 
lEHMOVE deletes the work data set at the completion of the program, it can be 
contained on the receiving volume, provided there is room for it.) 

• DDl DD defines the system residence device. The system residence volume 
contains the entries to be moved. 

• DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies a move operation for selected entries and defines the receiving 
volume. 

In this example, a volume of data sets is to be moved to a 2314 volume. All data sets 
that are successfully moved are scratched from the source volume; however, any 
catalog entries pertaining to those data sets are not changed. Space is allocated by 
lEHMOVE. The work data set is deleted when the job step is completed. 

The example follows: 



//MOVEVOL 
// 



JOB 09#550, GREEN 
EXEC PGM=IEHMOVE 



//SYSPRINT DD 

//SYSUTl 

//DDl 

//DD2 

//DD3 

//SYSIN 



/* 



DD 
DD 
DD 
DD 
DD 
MOVE 



SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 

UNIT=23 1 4 , VOLUME=SER=23 1 401, DISP=OLD 

* 

VOLUME=23 1 4=23 1 401 , TO=23 1 4=23 1400 , PASSWORD 
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The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. The work data 
set is removed from the receiving volume when the job step is completed. 

• DDl DD defines the system residence device. 

• DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 

• DD3 DD defines a mountable device on which the source volume is to be mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies a move operation for a volume of data sets and defines the source 
and receiving volumes. This statement also indicates that password -protected data 
sets are to be included in the operation. 

Note: lEHPROGM can be used to uncatalog catalog entries pertaining to source data 
sets and to catalog the moved versions of those data sets. 

In this example, a partitioned data set is to be moved to a 2314 volume on which 
space has been previously allocated for the data set. The source data set is 
scratched. The work data set is deleted when the job step is completed. 

The example follows: 

//ALLOCATE JOB 09#550, GREEN 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//SET1 DD DSNAME=PDSSET1 ,UNIT=2314,DISP=(NEW,KEEP), 

// VOLUME=SER=231401 , SPACE=( TRK, ( 100, 10,10) ), 

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=2000) 

//SYSIN DD * 

/* 

// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 40 1 , DISP=OLD 
UNIT=2301 ,V0LUME=SER=1 11111 ,DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1401, DISP=OLD 
UNIT=23 1 4 , VOLUME=SER=23 1402, DISP=OLD 
* 

PDS=PDSSET1 ,TO=23 14=23 1401 ,FROM=23 14=23 1402 
/* 

The lEHPROGM job step is used to allocate space for data set PDSSETl on a 2314 
volume. 

The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. The data set is 
removed from the receiving volume at the completion of the program. 

• DDl DD defines the system residence device. 

• DD2 DD defines the device on which the receiving volume is to be mounted. 

• DD3 DD defines a mountable device on which the source volume is to be mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies a move operation for the partitioned data set PDSSETl and defines 
the source and receiving volumes. 



//SYSUTl 


DD 


//DDl 


DD 


//DD2 


DD 


//DD3 


DD 


//SYSIN 


DD 




MOVE 
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lEHMOVE Example 9 In this example, three partitioned data sets are to be moved from three separate 

source volumes to a 2311 volume. The source data set PDSSET3 is unloaded. (The 
record size exceeds the track capacity of the receiving volume.) The work data set is 
deleted when the job step is completed. 

The example follows: 

//ALLOCATE JOB 09 #550, GREEN 
// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//SET1 DD DSNAME=PDSSET1 ,UNIT=231 1 ,DISP={ NEW, KEEP), 
// VOLUME=SER=231 101 , SPACE=( TRK, ( 100, 10,5 ) ), 
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=1600 ) 

//SET2 DD DSNAME=PDSSET2,UNIT=2311 ,DISP=(NEW,KEEP), 
// VOLUME=SER=231 101 , SPACE=( TRK, ( 50 , 5 , 5 ) ), 
// DCB=(RECFM=F,LRECL=80,BLKSIZE=80 ) 

//SET3 DD DSNAME=PDSSET3,UNIT=231 1 ,DISP=( NEW, KEEP), 
// VOLUME=SER=231101 , SPACE=( TRK, ( 50 , 5 ) ), 
// DCB=(RECFM=U,BLKSIZE=5000 ) 
* 

PGM=IEHMOVE 
SYSOUT=A 

UNIT=2311 ,VOLUME=SER=231 101 ,DISP=OLD 
UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 
UNIT=( 2314,, DEFER ) , DISP=OLD , 
:( PRIVATE, ,SER=( 231400 ) ) 

UNIT=231 1 ,VOLUME=SER=231 101 ,DISP=OLD 
* 

PDS=PDSSET1 ,TO=231 1=231 101 , FROM=23 14=23 1400 
PDS=PDSSET2,TO=231 1=231 101 , FROM=23 14=23 1 40 1 
PDS=PDSSET3,TO=231 1=231 101 , FROM=23 1 4=23 1402 
/* 

The lEHPROGM job step is used to allocate space for the partitioned data sets 
PDSSETl, PDSSET2, and PDSSETS on the receiving volume. The SPACE parameter in 
the SETS DD statement allocates space for a sequential data set. This is necessary to 
successfully unload the partitioned data set PDSSETS. The DCB attributes of PDSSETS 
are: 

DCB = (RECFM = U.BLKSIZE = 5000) 
The unloaded attributes are: 

DCB = (RECFM = FB,LRECL = 80,BLKSIZE = 800) 
The control statements are discussed below: 

• SYSUTl DD defines the device that Is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volumes are mounted as 
they are required. 

• DD3 DD defines a mountable device on which the receiving volume is mounted. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE specifies move operations for the partitioned data sets and defines the 
source and receiving volumes. 

Note: For a discussion on estimating space allocations, refer to OS Data Management 
Services Guide, GC26-S746. 



//SYSIN 


DD 


/* 




// 


EXEC 


//SYSPRINT DD 


//SYSUTl 


DD 


//DDl 


DD 


//DD2 


DD 


// VOLUME=(PRIV. 


//DD3 


DD 


//SYSIN 


DD 




MOVE 




MOVE 




MOVE 



lEHMOVE Program 25S 



lEHMOVE Example 10 



lEHMOVE Example 11 



In this example, a sequential data set is to be unloaded onto a 9-track, unlabeled tape 
volume (800 bits per inch). The work data set resides on the source volume and is 
deleted when the job step is completed. 

The example follows: 



09#550, GREEN 
PGM=IEHMOVE 
SYSOUT=A 

UNIT=23 1 4 , VOLUME=SER=23 1 400 , DISP=OLD 
UNIT=231 1 ,V0LUME=SER=1 11111 ,DISP=OLD 
UNIT=2 314, VOLUME=SER=23 1400, DISP=OLD 
UNIT=2400 , VOLUME=SER=SCRTCH , DISP=OLD , 
,NL) 



//UNLOAD JOB 

// EXEC 

//SYSPRINT DD 

//SYSUT1 DD 

//DD1 DD 

//DD2 DD 

//TAPEOUT DD 

// DCB=(DEN=2),LABEL= 

//SYSIN DD * 

MOVE DSNAME=SEQSET1 ,TO=2400=SCRTCH, »C 

FROM=23 1 4=23 1 400 , TODD=TAPEOUT 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the source volume is mounted. 

• TAPEOUT DD defines a mountable device on which the receiving tape volume is 
mounted. This statement also provides label and mode information. 

• SYSIN DD defines the control data set which follows in the input stream. 

• MOVE moves the sequential data set SEQSETl from a 2314 volume to the 
receiving tape volume. The data set is unloaded. The TODD parameter in this 
statement refers to the TAPEOUT DD statement for label and mode information. 

In this example, three unloaded sequential data sets are to be loaded from a labeled, 
7-track tape volume (556 bits per inch) to a 2314 volume. Space is allocated by 
lEHMOVE. The example assumes that the 2314 volume is capable of supporting the 
data sets in their original forms. 

The example follows: 

//LOAD JOB 09#550, GREEN 

// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//DDl DD UNIT=3330,VOLUME=SER=111111 ,DISP=OLD 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//TAPESETS DD DSNAME=UNLDSET1 ,UNIT=2400 , VOLUME=SER=001 234 , 

// DISP=OLD , LABEL=( 1 , SL ) , DCB=( DEN= 1 , TRTCH=C ) 

//SYSIN DD * 

MOVE DSNAME=UNLDSET1 , TO=23 1 4=23 1 400 , ^C 

FROM=2400-2=( 001234,1 ) , FROMDD=TAPESETS 

MOVE DSNAME=UNLDSET2,TO=23 14=23 1400, llC 

FROM=2400=( 001234,2 ),FROMDD=TAPESETS 

MOVE DSNAME=UNLDSET3,TO=23 14=23 1400, nc 

FROM=2400=( 001234,3 ),FROMDD=TAPESETS 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the device that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the receiving volume is mounted. 

• TAPESETS DD defines a mountable device on which the source volume is mounted. 
DOB information is provided in this statement. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• MOVE moves the unloaded data sets to the receiving volume. 

Note: To move a data set from a tape volume that contains more than one data set, 
you must specify the sequence number of the data set in the list field of the FROM or 
TO parameter on the utility control statement. 
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In this example, two sequential data sets are to be copied from separate source 
volumes to a 2314 volume. Space is allocated by lEHMOVE. Only one 9-track tape 
drive is available for the operation. 

The example follows: 

//DEFER JOB 09 #550, GREEN 

// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//DD1 DD UNIT=231 1 ,V0LUME=SER=1 11 1 1 1 ,DISP=OLD 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//TAPE1 DD DSNAME=SEQSET1,UNIT=2400,DISP=OLD, 

// LABEL=( ,SL),VOLUME=SER=01234,DCB=(DEN=2) 

//TAPE2 DD DSNAJyiE=SEQSET9,UNIT=AFF=TAPE1 ,DISP=OLD, 

// LABEL=( 4 , SL) , VOLUME=SER=0 1235, DCB=( DEN=2 ) 



//SYSIN 



/' 



DD 
COPY 

COPY 



DSNAME=SEQSET1 ,TO=231 4=23 1400 , 
FROM=2400=( 001234,2), FR0MDD=TAPE1 

DSNAME=SEQSET9 , TO=23 1 4=23 1 400 , 
FROM=2400=( 001235,4 ),FR0MDD=TAPE2 



lie 
lie 



The control statements are discussed below: 

• SYSUTl DD defines the volume that is to contain the work data set. 

• DDl DD defines the system residence device. 

• DD2 DD defines a mountable device on which the receiving volume is mounted. 

• TAPEl DD defines a mountable device on which the first volume to be processed is 
mounted. The source data set is the second data set on the volume, as specified in 
the utility control statement. 

• TAPE2 DD defines a mountable device on which the second volume to be 
processed is mounted when it is required. The source data set is the fourth data set 
on the volume, as specified in the utility control statement. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COPY copies the data sets to the receiving volume. 

Note: To copy a data set from a tape volume that contains more than one data set, 
you must specify the sequence number of the data set in the list field of the FROM or 
TO parameter on the utility control statement. 

In this example, three unloaded partitioned data sets residing on an unlabeled tape 
volume mounted on device 282 are copied to a 2314 volume mounted on device 191. 

The example follows: 

//LOAD JOB MEDDAUGH,PS403 00439, MSGLEVEL=1 
// EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 
SYSOUT=A 

UNIT=1 9 1 , VOLUME=SER=23 1 400 , DISP=OLD 
UNIT= 191, VOLUME=SER=23 1 400 , DISP=OLD 
UNIT=282,VOLUME=SER=NLTAPE,DISP=OLD, 
// LABEL=( ,NL),DCB={RECFM=FB,LRECL=80,BLKSIZE=800) 
//SYSIN DD * 
COPY PDS=DSET1 ,FROM=282=(NLTAPE,1 ) ,T0=1 91 =23 1 400 ,FR0MDD=TAPE1 
COPY PDS=DSET2 , FROM=282=( NLTAPE , 2 ) , T0= 1 9 1 =23 1 400 , FR0MDD=TAPE 1 
COPY PDS=DSET3 , FROM=282=( NLTAPE , 3 ) , T0= 191=23 1400 , FROMDD=TAPE 1 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the work data set. 

• TAPEl DD defines the source data sets. They are, in the order in which they reside 
on the volume, DSETl, DSET2, and DSET3. 

• DDl DD defines the receiving volume. 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COPY copies the unloaded partitioned data sets from the unlabeled tape to the 
receiving volume. 



//SYSABEND DD 
//SYSUTl DD 
//DDl DD 
//TAPEl DD 



lEHMOVE Program 255 



lEHMOVE Example 14 



Note: To copy data sets from a nonlabeled tape, you must place a label In the list field 
of the FROM parameter of the utility control statement. Following this label, the 
sequence numbers of the data sets must also be included in the same field. The unit 
address must appear in the device field of the FROM or TO parameter whenever you 
want to move from or copy to a specific device. 

In this example, a BDAM data set on two 2314 volumes is copied to a 3330 disk 
storage device and is renamed. Space is allocated by lEHMOVE. 

The example follows: 

JOB 09#550, GREEN 

EXEC PGM= lEHMOVE 
SYSOUT=ii 

UNIT=3330,VOL=SER=333001 ,DISP=OLD 
UNIT=2314,VOL=SER=1 11111 ,DISP=OLD 
UNIT=( 2314,2 ),VOL=SER=( 231401 , 23 1 402 ) ,DISP=OLD 
UNIT=3330,VOL=SER=333001 ,DISP=OLD 
* 

COPY FR0M=2314=( 231401, 231402 ),TO=3330=333001, SC 

DSNAME=TWOVOL . BDAM , RENAME=ONEVOL . BDAM 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the work data set. 

• DDl DD defines the system residence device on which the source volumes reside. 

• DD2 DD defines the two mountable volumes to be copied. Both volumes must be 
mounted in parallel. 

• DD3 DD defines the receiving volume, 

• SYSIN DD defines the control data set, which follows in the input stream. 

• COPY copies the data set to the receiving volume and renames it. 



//COPYBDAM 




// 




//SYSPRINT 


DD 


//SYSUTl 


DD 


//DDl 


DD 


//DD2 


DD 


//DD3 


DD 


//SYSIN 


DD 
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Scratching a Data Set 
or Member 



Renaming a Data Set 
or IVIember 



Cataloging or Uncataloging 
a Data Set 



lEHPROGM is a system utility used to modify system control data and to maintain data 
sets at an organizational level. (See "Introduction" for general system utility 
information.) 

lEHPROGM can be used to: 

• Scratch a data set or a member. 

• Rename a data set or a member. 

• Catalog or uncatalog a data set. 

• Build or delete an index or an index alias. 

• Connect or release two volumes. 

• Build and maintain a generation index. 

• Maintain data set passwords. 

At the completion or termination of the program, the highest return code encountered 
within the program is passed to the calling program. 

lEHPROGM can be used to scratch the following from a direct access volume or 
volumes: 

• Sequential, indexed sequential, partitioned, or direct access data sets. 

• Members of a partitioned data set. 

• Password -protected data sets. 

• Data sets named by the operating system. 

A data set is considered scratched when its data set control block is removed from 
the volume table of contents (VTOC) of the volume on which it resides; its space is 
made available for re-allocation. 

The space occupied by a data set residing on a device that operates in split-cylinder 
mode is not available for re-allocation until all data sets sharing the cylinder have 
been scratched. 

A member is considered scratched when its name is removed from the directory of the 
partitioned data set that contains it. The space occupied by a scratched member is 
not available for re-allocation until the partitioned data set is scratched, or the data 
set is compressed in place. (When scratching a member of a partitioned data set, all 
aliases of that member should also be removed from the directory.) 

lEHPROGM can be used to rename a data set or member that resides on a 

direct access volume. In addition, the program can be used to change any member 

aliases. 

lEHPROGM can be used to catalog or uncatalog a sequential, indexed sequential, 
partitioned, or BDAM data set. 

A data set is cataloged when its fully-qualified name and volume identification are 
entered in one or more index levels of the SYSCTLG data set. The program catalogs a 
data set by generating an entry, containing the data set name and associated volume 
information, in the index of the catalog. If higher level indexes are necessary to 
catalog the data set, they are automatically created. 

The catalog function is used to: (1) catalog a data set that was not cataloged when it 
was created or (2) satisfy, if necessary, the requirement that a higher level index or 
indexes be created. Figure 54 shows how data set A.F.G is cataloged on the system 
residence volume. Note that the level F index does not exist in the SYSCTLG data set 
before the catalog operation. 

lEHPROGM uncatalogs a data set by removing the data set name and associated 
volume information from the lowest level index of the catalog. 

The uncatalog function of the program differs from a DISP = (...,UNCATLG) 
specification in a DD statement in that the DISP = (...,UNCATLG) specification cannot 
remove an entry from the SYSCTLG data set on a volume other than the system 
residence volume unless the two volumes are properly connected. 
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System residence- 
before cataloging A.F.G. 



System residence- 
after cataloging A.F.G. 
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Using lEHPROGM 



Figure 55 shows how data set A.F.G is uncataloged by the program. Prior to the 
operation, the fully qualified name and associated volume information are represented 
in the catalog. The uncatalog operation removes the lowest level entry from the index 
structure. Note that the structure A.F remains in the catalog. 



System residence- 
prior to uncataloging A.F.G. 



System residence- 
after uncata'oging A.F.G. 





Figure 55. Uncataloging a Data Set Using lEHPROGM 



lEHPROGM can be used to build a new index in the catalog or to delete an existing 
index. In building an index, the program automatically creates as many higher level 
indexes as are necessary to complete the specified structure. 

lEHPROGM can be used to delete one or more indexes from an index structure; 
however, an index cannot be deleted if it contains any entries. That is, it cannot be 
deleted if it refers to a lower level index or if it is part of a structure indicating the 
fully-qualified name of a cataloged data set. 

Figure 56 shows an index structure before and after a build operation. The left-hand 
portion of the figure shows two cataloged data sets, A.Y.YY and A.B.X.XX, before the 
build operation. The right-hand portion of the figure shows the index structure after 
the build operation, which was used to build index A.B.C.D.E. Note in the left-hand 
portion of the figure that index levels C and D do not exist before the build operation. 
These levels are automatically created when the level E index is built. 

Note that when the level E index is subsequently deleted, the level and D indexes 
are not automatically deleted by the program. To delete these index levels, delete: 
A.B.C.D.E, A.B.C.D, and A.B.C, in that order. The level B index cannot be deleted 
because data set A.B.X.XX and the X level index are dependent upon the level B index. 
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Figure 56. Index Structure Before and After an lEHPROGM Build Operation 

lEHPROGM can be used to assign an alternative name (alias) to the higiiest level 
index of a catalog or to delete an alias previously assigned. An alias cannot, however, 
be assigned to the highest level of a generation index. 

Figure 57 shows an alias, XX, that is assigned to index A (a high level index). The 
cataloged data set A.B.C can be referred to as either A.B.C or XX.B.C. 




Figure 57. Building an Index Alias Using lEHPROGM 



lEHPROGM can be used to connect a volume to a second volume by placing an entry 
(that contains an index name and the volume serial number and device type of the 
second volume) into a high level index on the first volume. The program can 
subsequently release the volumes by removing the entry from the high level index. If 
two volumes are connected: 

• The catalog (SYSCTLG data set) can be extended to a second volume, if necessary. 

• Normal JCL can be used to process (retrieve, uncatalog, etc.) data sets cataloged 
on the second volume (assuming that the first volume is the system residence 
volume). 

If the SYSCTLG data set is extended to a second volume, it must be identified on that 
volume. 

Figure 58 shows how the system residence volume can be connected to a second 
volume. Any subsequent index search for index X on the system residence volume is 
carried to the second volume. 

Note: The index name of each high level index existing on the second volume must be 
present in the first volume; when a new high level index is placed on a second volume, 
the second volume should be connected to the first volume. 

Figure 59 shows three volumes connected to the system residence volume. All 
volumes are accessible (through high level indexes X, Y, and Z) to the operating 
system. 
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Figure 58. Connecting a Volume to a Second Volume Using lEHPROGM 



System residence 



System residence 



Building and Maintaining a 
Generation Index 




FC 






Volume 2 






Figure 59. Connecting Three Volumes Using lEHPROGM 



lEHPROGM can be used to build an Index structure for a generation data group and 
to control the action to be taken if the index overflows. 

The lowest level index in the structure can contain up to 255 entries for successive 
generations of a data set. If the index overflows, the oldest entry is removed from the 
index, unless otherwise specified (in which case all entries are removed). If desired, 
the program can be used to scratch all generation data sets whose entries are 
removed from the index. 

Figure 60 shows the index structure created for generation data group A.B.C. In this 
example, provision is made for up to five subsequent entries in the lowest level index. 




Figure 60. Building a Generation Index Using lEHPROGM 



Note: Before a generation data group can be cataloged as such, a generation index 
must exist. Otherwise, a generation data set is cataloged as an individual data set, 
rather than as a generation. 
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When creating and cataloging a generation data set, the user can provide necessary 
DCB information. See "Providing DCB Attributes" in "Appendix D: Generation Data 
Groups" for a discussion of how DCB attributes are provided for a generation data 
group. 

lEHPROGIVI can be used to maintain password entries in the PASSWORD data set and 
to alter the protection status of direct access data sets in the data set control block 
(DSCB). For a complete description of data set passwords and the PASSWORD data 
set OS Data Management for System Programmers, GC28-6550. 

A data set can have one of three types of password protection, as indicated in the 
DSCB for direct access data sets and in the tape label for tape data sets (see OS 
System Control Blocks, GC28-6628, for a description of the DSCB and tape label). The 
possible types of data set password protection are: 

• No protection, which means that no passwords are required to read or write the 
data set. 

• Read/write protection, which means that a password is required to read or write 
the data set. 

• Read-without-password protection, which means that a password is required only 
to write the data set; the data set can be read without a password. 

Note: If a system data set is password protected and a problem occurs on a system 
data set, maintenance personnel must be provided with the password in order to 
access the data set and resolve the problem. 

A data set can have one or more passwords assigned to it; each password has an 
entry in the PASSWORD data set. A password assigned to a data set can allow read 
and write access or only read access to the data set. 

Figure 61 shows the relationship between the protection status of data set ABC and 
the type of access allowed by the passwords assigned to the data set. Passwords 
ABLE and BAKER are assigned to data set ABC. If no password protection is set in the 
DSCB or tape label, data set ABC can be read or written without a password. If 
read/write protection is set in the DSCB or tape label, data set ABC can be read with 
either password ABLE or BAKER and can be written with password ABLE. If 
read-without-password protection is set in the DSCB or tape label, data set ABC can 
be read without a password and can be written with password ABLE; password BAKER 
is never needed. 
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allows read access 



Password ABLE for data_set ABC 
allows read/write access 




Figure 61. Relationship Between the Protection Status of a Data Set and Its 
Passwords 

Before lEHPROGM is used to maintain data set passwords, the PASSWORD data set 
must reside on the system residence volume. lEHPROGM can then be used to: 

• Add an entry to the PASSWORD data set. 

• Replace an entry in the PASSWORD data set. 

• Delete an entry from the PASSWORD data set. 

• Provide a list of information from an entry in the PASSWORD data set. 

Each entry in the PASSWORD data set contains the name of the protected data set, 
the password, the protection mode of the password, an access counter, and 77 bytes 
of optional user data. The protection mode of the password defines the type of access 
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allowed by the password and whether the password Is a control password or 
secondary password. Control and secondary passwords are discussed under "Adding 
Data Set Passwords" below. 

For direct access data sets, lEHPROGM updates the protection status in the DSCB 
when a control password entry is added, replaced, or deleted. This permits setting and 
resetting the protection status of an existing direct access data set at the same time 
its passwords are added, replaced, or deleted. lEHPROGM automatically alters the 
protection status of a data set in the DSCB if the following conditions are met: 

• The control password for the data set is being added, replaced, or deleted. (The 
control password for a data set is the initial password entry in the PASSWORD data 
set for that data set name.) 

• The data set is on line. 

• The volume on which the data set resides Is specified on the utility control 
statement, or the data set is cataloged. 

• The data set is not allocated within the lEHPROGM job. 

For tape data sets, lEHPROGM cannot update the protection status In the tape label 
when a password entry is added, replaced, or deleted. Protection status in a tape label 
must be set via job control language. 

Passwords to be added, replaced, deleted, or listed can be specified on utility control 
statements or can be entered by the console operator. lEHPROGM issues a message 
to the console operator when a password on a utility control statement is either 
missing or invalid. The message contains the job name, step name, and utility control 
statement name and identifies the particular password that is missing or invalid. Two 
invalid passwords are allowed per password entry on each utility control statement 
before the request is ignored; a total of five invalid passwords is allowed for the 
password entries on all the utility control statements in a job step before the step Is 
canceled. 

When a password is added for a data set, an entry Is created in the PASSWORD data 
set with the specified data set name, password name, protection mode of the 
password (read/write or read-only), and the optional 77 characters of user-supplied 
data. The access counter in the entry is set to zero. 

If this is the first password added to the PASSWORD data set for a data set, the 
password is marked in the entry as the control password for that data set. The second 
and subsequent passwords added for the same data set are marked as secondary 
passwords. The control password for a data set must always be specified to add, 
replace, or delete secondary passwords. The control password should not be 
specified, however, to list information from a secondary password entry. 

Secondary passwords can be assigned to a data set to restrict some users to reading 
the data set or to record the number of times certain users access the data set. The 
access counter in each password entry provides a count of the number of times the 
password was used to successfully open the data set. 

If a control password for a direct access, online data set Is added, the protection 
status of the data set (read/write or read-without-password) is set in the DSCB. 
However, the data set to be protected must not be allocated within the same job as 
the one in which lEHPROGM is executed. If it is allocated, the DSCB cannot be 
accessed and the protection status is not set. If the data set to be protected is being 
created within the same job, use job control language to set the protection status in 
the DSCB. 

Any of the following Information may be replaced in a password entry: the password, 
protection mode (read/write or read-only) of the password, and the 77 characters of 
user data. The access counter of the password entry is set to zero when any 
information In the entry is replaced. The protection status of a data set can be 
changed by replacing the control entry for the data set. 

If the control entry of a direct access, online data set is replaced, the DSCB is also 
reset to indicate any change in the protection status of the data set. Therefore, the 
user should ensure that the volume Is on line when changing the protection status of a 
direct access data set. 

When a control password entry is deleted from the PASSWORD data set, all secondary 
password entries for that data set are also deleted. However, when a secondary entry 
is deleted, no other password entries are deleted. 

If the control password entry is deleted for an online, direct access data set, the 
protection status of the data set in the DSCB is also changed to indicate no 
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protection. When deleting a control password for a direct access data set, the user 
should ensure that the volume is on line. If the volume is not on line, the password 
entry is removed, but data set protection is still indicated in the DSCB; the data set 
cannot be accessed unless another password is added for that data set. 

If the control password entry is deleted for a tape data set, the user must change the 
protection status in the tape label to indicate no protection; otherwise, the data set 
cannot be accessed. The tape label may be changed using the lEHINITT utility 
program. 

The delete function should be used to delete all the password entries for a scratched 
data set to make the space available for new entries. 

A list of information from any entry in the PASSWORD data set can be obtained in the 
SYSPRINT data set by providing the password for that entry. The list includes: the 
number of times the password has been used to successfully open the data set; the 
type of password (control password or secondary password) and type of access 
allowed by the password (read/write or read-only); and the user data in the entry. 
Figure 62 shows a sample list of information printed from a password entry. 

DECIMAL ACCESS COUNT= 000025 

PROTECT MODE BYTE= SECONDARY, READ ONLY 

USER DATA FIELD= ASSIGNED TO J. BROWN 

Figure 62. Listing of a Password Entry 

lEHPROGM uses as input a control data set that contains utility control statements 
used to control the functions of the program and to indicate those data sets or 
volumes that are to be modified. 

lEHPROGM produces as output a modified object data set or volume(s) and a 
message data set, which contains any error messages and information from the 
PASSWORD data set. 

lEHPROGM provides a return code to indicate the results of program execution. The 
return codes and their meanings are: 

• 00, which indicates successful completion. 

• 04, which indicates that a syntax error was found in the name field of the control 
statement or In the PARM field in the EXEC statement. Processing is continued. 

• 08, which indicates that a request for a specific operation was ignored because of 
an invalid control statement or an otherwise invalid request. The operation is not 
performed. 

• 12, which indicates that an input/output error was detected when trying to read 
from or write to SYSPRINT, SYSIN or the VTOC. 

• 16, which indicates an unrecoverable error. The job step is terminated. 
lEHPROGM is controlled by job control statements and utility control statements. 
Job control statements are used to: 

• Execute or invoke the program. 

• Define the control data set. 

• Define volumes and/or devices to be used during the course of program execution. 

• Prevent data sets from being deleted inadvertently. 

• Prevent volumes from being demounted before they have been completely 
processed by the program. 

• Suppress listing of utility control statements. 

Utility control statements are used to control the functions of the program and to 
define those data sets or volumes that are to be modified. 
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Table 53 shows the job control statements necessary for using lEHPROGM. 



Table 53. lEHPROGM Job Control Statements 



Restrictions 



Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = lEHPROGM) or, if the job control statements 

reside in a procedure library, the procedure name. Additional PARM information 
can be specified to control the line density on the output listing and to suppress 
printing of utility control statements. See "PARM Information on the EXEC 
Statement" below. 

SYSPRINT DD Defines a sequential message data set. 

anynamel DD Defines a permanently mounted volume. (The system residence volume is 
considered to be a permanently mounted volume.) 

anyname2 DD Defines a mountable device type. 

SYSIN DD Defines the control data set. The control data set normally follows the job control 

statements in the input stream; however, it can be defined as a member of a 
procedure library. 

The minimum region size that can be specified for the execution of lEHPROGM is 44K. 

The anynamel DD statement can be entered: 

//anynamel DD UNIT = xxxx,VOLUME = SER = xxxxxx.DISP = OLD 

The UNIT and VOLUME parameters define the device type and volume serial number. 
The DISP = OLD specification prevents the inadvertent deletion of a data set. The 
anynamel DD statement is arbitrarily assigned the ddname DDl in the lEHPROGM 
examples. 

The anyname2 DD statement can be coded in the following ways: 

//anyname2 DD VOLUME = SER = xxxxxx,UNIT = xxxx,DISP = OLD 

//anyname2 DD VOLUME = (PRIVATE,SER = xxxxxx), 
// UNIT = (xxxx„DEFER),DISP = OLD 

The second example can be used to specify deferred mounting when a large number 
of magnetic tapes or direct access volumes are to be processed in one application of 
the program. The anyname2 DD statement is arbitrarily assigned the ddname DD2 in 
the lEHPROGM examples. DD statements defining additional mountable devices are 
assigned names DD3, DD4, etc. 

Refer to "Appendix C: DD Statements for Defining Mountable Devices" for 
instructions on defining mountable volumes. 

• The block size for the SYSPRINT (message) data set must be a multiple of 121. 
The block size for the SYSIN (control) data set must be a multiple of 80. Any 
blocking factor can be specified for these block sizes. 

• With the exception of the SYSIN and SYSPRINT DD statements, all DD statements 
in Table 53 are used as device allocation statements, rather than as true data 
definition statements. Because lEHPROGM modifies the internal control blocks 
created by device allocation DD statements, these statements must not include the 
DSNAME parameter. (All data sets are defined explicitly or implicitly by utility 
control statements.) 

• One anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. 

• One anyname2 DD statement must be included for each mountable device to be 
used in the job step. 

• When lEHPROGM is dynamically invoked in a job step containing a program other 
than lEHPROGM, the DD statements defining mountable devices for lEHPROGM 
must be included in the job stream prior to DD statements defining data sets 
required by the other program. 

• For MVT applications, DD statements defining mountable devices must appear in 
the same order in the input stream as the utility control statements that refer to 
volumes mounted on those devices. 

• When VOL = device = list specifies multiple volumes, no more than 50 volumes 
may be specified. 
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Additional information can be specified in tlie PARM parameter of the EXEC 
statement to control line density on the output listing and to suppress printing of utility 
control statements. The EXEC statement can be coded: 



Utility Control Statements 



SCRATCH Statement 



//EXEC PGM = IEHPROGM[,PARM = 'LINECNT = xx, 



{ PRINT }'] 
{NOPRINT } 



The LINECNT parameter specifies the number of lines per page in the listing of the 
SYSPRINT data set; xx is a 2-digit number, from 01 through 99. If LINECNT is 
omitted, or if an error is encountered in the LINECNT subparameter, the number of 
lines per page will be 45. 

The PRINT value specifies that the utility control statements are to be written to the 
SYSPRINT data set. If neither PRINT nor NOPRINT is coded, PRINT is assumed. 

The NOPRINT value specifies that utility control statements are not to be written to 
the SYSPRINT data set Suppressing printing of utility control statements assures that 
passwords assigned to data sets remain confidential. However, suppressing printing 
may make it difficult to interpret error messages because the relevant utility control 
statement is not printed before the message. 

lEHPROGM is controlled by the following utility control statements: 

SCRATCH statement, which is used to scratch a data set or a member from a direct 
access volume. 

RENAME statement, which is used to change the true name or alias of a data set or 
member residing on a direct access volume. 

CATLG statement, which is used to generate an entry in the index of a catalog. 

UNCATLG statement, which is used to remove an entry from the lowest level index 
of the catalog. 

BLDX statement, which is used to create a new index in the catalog. 

DLTX statement, which is used to remove a low level index from the catalog. 

BLDA statement, which is used to assign an alias to an index at the highest level of 
the catalog. 

DLTA statement, which is used to deiete an alias previously assigned to an index at 
the highest level of the catalog. 

CONNECT statement, which is used to place an entry into an index at the highest 
level of the catalog. 

RELEASE statement, which is used to remove an entry from the high level index of 
a volume. 

BLDG statement, which is used to build an index for a generation data group and to 
establish the action to be taken should the index overflow. 

ADD statement, which is used to add a password entry in the PASSWORD data set. 

REPLACE statement, which is used to replace information in a password entry. 

DELETER statement, which is used to delete an entry in the PASSWORD data set. 

LIST statement, which is used to format and print information from a password 
entry. 

The SCRATCH statement is used to scratch a data set or member from a direct 
access volume. A data set or member is scratched only from the volumes designated 
in the SCRATCH statement. This function does not uncatalog scratched data sets. 

The format of the SCRATCH statement is: 

[label] SCRATCH {DSNAME = name } i 

{VTOC } 

,VOL = device = list 

[.PURGE] 

[.MEMBER = name] 

._ [,SYS] 

where: 

DSNAME = name 

specifies the fully-qualified name of either the data set to be scratched or the 
partitioned data set that contains the member to be scratched. 
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VTOC 

specifies that all data sets on the specified volume, except those protected by a 
password or those whose expiration dates have not expired, are to be scratched. 
Password -protected data sets are scratched if the correct password is provided. 
The effect of VTOC is modified when it is used with PURGE or SYS. 

VOL = device = list 

specifies the volume or volumes that contain the data set or sets to be scratched. If 
VTOC is specified, VOL cannot specify more than one volume. Caution should be 
used when specifying VTOC if VOL specifies the system residence volume. 

PURGE 

specifies that each data set specified by DSNAME or VTOC be scratched, even if its 
expiration date has not elapsed. If PURGE is omitted, the specified data sets are 
scratched only if their expiration dates have elapsed. 

MEMBER = name 

specifies a member name or alias of a member to be removed from the directory of 
a partitioned data set. If MEMBER is omitted, the entire data set or volume of data 
sets is scratched. 

SYS 

specifies that data sets that are to be scratched have names that begin with 
"AAAAAAAA.AAAAAAAA.AAAAAAAA.AAAAAAAA." or "SYSnnnnn.T and F or V in 
position 19. These are names assigned to data sets by the operating system. This 
parameter is valid only when VTOC is specified. 

If the name of the data set to be scratched begins with SYS, nnnn is the date and F or 
V in position 19 represents MFT or MVT. 

When executing a SCRATCH operation, care should be taken to ensure that the data 
set or volume is not being used by a program executing concurrently. 

The RENAME statement is used to change the true name or alias of a data set or 
member residing on a direct access volume. The name is changed only on the 
designated volume(s). The rename operation does not update the catalog. 

The format of the RENAME statement is: 

[/abe/] RENAME DSNAME -name 

,VOL = device = list 
.NEWNAME = name 
[.MEMBER = name] 
where: 

DSNAME = name 

specifies the fully-qualified name of the data set to be renamed or specifies the 
data set that contains the member to be renamed. 

VOL = device = list 

specifies the volume or volumes that contain the data set or member whose name 
is to be changed. If MEMBER is specified, VOL cannot specify more than one 
volume. 

NEWNAME = name 

specifies the new fully-qualified name for the data set, or the new member or alias. 

MEMBER = name 

specifies the member name or alias for a member (in the named data set) that is to 
be renamed. If MEMBER is omitted, the specified data set name is changed. 

The CATLG statement is used to generate an entry in the index of a catalog. If 
additional levels of indexes are required in the catalog, this function automatically 
creates them. When cataloging generation data sets, refer to "BLDG (Build Generation 
Index) Statement" for the action to be taken when the index is full. 

The format of the CATLG statement is: 

[/abefj CATLG DSNAME = name 

,VOL = device = list 
[,CVOL = device — serial] 
where: 

DSNAME = name 

specifies the fully-qualified name of the data set to be cataloged. The qualified 
name must not exceed 44 characters, including delimiters. 
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VOL = device = list 

specifies the volume or volumes that contain the data set to be cataloged. For 
either a sequential data set or an indexed sequential data set, the volume serial 
numbers must appear in the same order in which they were originally encountered 
(in DD statements within the input stream) when the data set was created. All serial 
numbers specified in VOL must represent the same device type. 

CVOL = device = serial 

specifies the device type and volume serial number of the control volume on which 
the catalog search for the index is to begin. If CVOL is omitted, the system 
residence volume is assumed. If the volumes are connected at the highest level of 
the index and the control volume is mounted, CVOL need not be specified. 

Note: When device is represented by a group name (for example, SYSDA) instead of a 
generic name (for example, 2314 or 2400) in the VOL parameter, the catalog 
operation does not enter the device type code in the system catalog. Instead, it places 
a unique entry in the device type field of the catalog. The allocation of the device for 
this entry may not be satisfactory to the user. The generic name should be used if the 
group name was generated for one or more device types. When the system is 
subsequently generated, this entry may no longer be valid; that is, all such group 
name entries should be uncataloged and then recataloged after a subsequent 
generation of the system. 

When cataloging data sets residing on tape, specify the data set sequence number 
and the volume serial number, as follows: 

VOL = device = ({serial,seqno},...) 

If a data set is created on a 9-track dual-density tape drive (2400-4), the data set 
can be cataloged with a device specification of 2400 for an 800 bits per inch tape or 
2400-3 for a 1600 bits per inch tape. If a device specification of 2400-4 is made 
when the data set is cataloged, any subsequent retrieval of that data set is made on a 
dual-density drive. 

The UNCATLG statement is used to remove an entry from the lowest level index of the 
catalog. This function does not delete higher level indexes from the index structure. 

The format of the UNCATLG statement is: 

I [/abe/] UNCATLG DSNAME = name 

I [,CVOL = device = serial] 

where: 

DSNAME= name 

specifies the fully-qualified name of the data set to be uncataloged. 

CVOL = device = serial 

specifies the device type and volume serial number of the control volume at which 
the search for the catalog entry is to begin. If CVOL is omitted, the system 
residence volume is assumed. If catalogs are properly connected at the highest 
level of the index and the control volume is mounted, CVOL need not be specified. 

The BLDX statement is used to create a new index in the catalog. If the creation 
of an index requires that higher level indexes be created, this function automatically 
creates them. 

The format of the BLDX statement is: 

; [/abefl BLDX ' Index « name' ^^"""™ ■"'"'•■''■' ' " ' ' . 1 

; ; [,CVOL = dev/ce = serial]^ ; __^ „___ ' j 

where: 

INDEX = name 

specifies the qualified name of the index to be created. The qualified name must 
not exceed 44 characters, including delimiters. 

CVOL = device = serial 

specifies the device type and volume serial number of the control volume on which 
the search for the index is to begin. If CVOL is omitted, the system residence 
volume is assumed. 

The DLTX statement is used to remove an index from the catalog. Only an index that 
has no entries can be removed. 

The format of the DLTX statement is: 

T'Oabe/] DLTX Index* name " ^■•■^-—■^■^^ .,™_,..„„„, 

t.CVOL =» deWce = ser/a/] I 
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where: 

INDEX = name 

specifies the qualified name of the index to be deleted. 

CVOL = device = serial 

specifies the device type and volume serial number of the control volume on which 
the search for the index is to begin. If CVOL is omitted, the system residence 
volume is assumed. 

Because this function does not delete higher level indexes, it must be used repetitively 
to delete an entire structure. For example, to delete index structure A.B.C, delete 
index A.B.C, index A.B, and index A. 

The BLDA statement is used to assign an alias to an index at the highest level of the 
catalog. 

The format of the BLDA statement is: 

i [/abeOBLDA INDEX = name ; 

! .ALIAS Aflame : 

j [,CVOL s= device « serfaO ^ _ _ '■ 

where: 

INDEX = name 

specifies the unqualified index to which an alias name is to be assigned. 

ALIAS = name 

specifies an unqualified name to be assigned as the alias. 

CVOL = device = serial 

specifies the device type and volume serial number of the control volume on which 
the catalog entry is to be made. If CVOL is omitted, the system residence volume is 
assumed. 

The DLTA statement is used to delete an alias previously assigned to an index at the 
highest level of the catalog. 

The format of the DLTA statement is: 

[label] DLTA ALIAS = name 

[,CVOL = device = serial] 
where: 

ALIAS = name 

specifies the unqualified index alias to be deleted. 

CVOL = device = serial 

specifies the device type and volume serial number of the control volume 
containing the catalog entry to be deleted. If CVOL is omitted, the system residence 
volume is assumed. 

The CONNECT statement is used to place an entry in the high level index of the 
catalog. The entry identifies a second volume by its device type and volume serial 
number. In addition, it contains an index name identifying the index to be searched for 
(during subsequent index searches) on the second volume. 

Note: This function does not create an index on the second volume. 

The format of the CONNECT statement is: 

[lat)el] CONNECT INDEX = name 

,VOL = device = serial 
[,CVOL = device = serial] 
where: 

INDEX = name 

specifies the index name to be entered in the high level index on the first volume. 

VOL = device = serial 

specifies the device type and volume serial number of the second volume. This 
information is placed in the high level index on the first volume. 

CVOL = device = serial 

specifies the device type and serial number of the first volume. If CVOL is omitted, 
the system residence volume is assumed to be the first volume. 
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The CONNECT statement does not create a SYSCTLG data set on the connected 
volume. Before cataloging the first data set on a connected volume, the user must 
define a SYSCTLG data set on that volume. This can be done with the following DD 
statement: 

//ddname DD DSNAME = SYSCTLG, UNIT = xxxx,DISP = (.KEEP), 
// SPACE = (CYL, 1),V0LUME = SEP = xxxxxx 

If a job requires an auxiliary control volume to complete a catalog search, the user 
need not have the auxiliary control volume mounted before the job is begun. (The user 
does not have to remember the volume on which a particular data set is cataloged.) 
The system directs the operator to mount an auxiliary control volume if it is needed. 
However, the auxiliary control volume must be connected to the system residence 
volume by means of the CONNECT verb, as modified for Release 17. If an auxiliary 
control volume was connected before Release 17, release the auxiliary control volume 
for all high level indexes on the system residence volume that point to that volume, 
and then use the current CONNECT verb to reconnect the auxiliary control volume 
with the system residence volume. 

The RELEASE statement Is used to remove an entry from the high level index of a 
volume. This effectively disconnects a second volume from the first volume. The 
RELEASE statement does not delete an index from the second volume. 

The format of the RELEASE statement is: 



[label] RELEASE INDEX = name 
[,CVOL = device 
where: 



serial] 



INDEX = name 

specifies the index name to be removed from the high level index of the first 
volume. 

CVOL = device = serial 

specifies the device type and volume serial number of the first volume. If CVOL is 
omitted, the system residence volume is assumed to be first volume. 

The BLDG statement is used to build an index for a generation data group, and to 
establish the action to be taken should the index overflow. 

The format of the BLDG statement is: 

[label] BLDG INDEX = name 
.ENTRIES = n 
[,CVOL = device = serial] 
[.EMPTY] 
[.DELETE] 
where: 

INDEX = name 

specifies the 1- to 35-character name of the generation index. 

ENTRIES = n 

specifies the number of entries to be contained in the generation index; n must not 
exceed 255. 

CVOL = device = serial 

specifies the device type and volume serial number of the volume on which the 
catalog search for the index is to begin. If CVOL is omitted, the system residence 
volume is assumed. 

EMPTY 

specifies that all entries be removed from the generation index when It overflows. 
This effectively uncatalogs all of the generation data sets. If EMPTY is omitted, the 
entries with the largest generation numbers will be maintained in the catalog when 
the generation index overflows. 

DELETE 

specifies that generation data sets are to be scratched after their entries are 
removed from the index. If DELETE is omitted, the data sets are not scratched. 

The ADD statement is used to add a password entry in the PASSWORD data set. 
When the control entry for a direct access, online data set is added, the indicated 
protection status is set in the DSCB; when a secondary entry is added, the protection 
status in the DSCB is not changed. 
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The format of the ADD statement is: 

^'"''[/abeO ADD'''dSNAME = name " ' "".' 

[,PASW0RD2 = new -password] 
i [.CPASWORD = control-password] 

[,TYPE = code] 
j [,VOL = device - list] I 

I [.DATA = 'user-dafa'] 

where: 

DSNAME = name 

specifies the fully-qualified name of the data set to which the password is to be 
assigned. 

PASW0RD2 = new-password 

specifies the password to be added. The password can consist of one- to 
eight-alphameric characters. If PASW0RD2 is omitted, the operator is prompted for 
a new password. 

CPASWORD = control -password 

specifies the control password for the data set. The control password must be 
specified unless this is the first password assigned to the data set. 

TYPE = code 

specifies the protection code of the password and, if a control password is being 
assigned to a direct access, online data set, specifies the protection status of the 
data set. If this parameter is omitted, the new password is assigned the same 
protection code as the control password for the data set. If a control password is 
being added, TYPE = 3 is the default. The values that can be specified for code are: 

1 

specifies that the password is to allow both read and write access to the data 
set; if a control password is being assigned, read/write protection is set in the 
DSCB. 

2 

specifies that the password is to allow only read access to the data set; if a 
control password is being assigned, read/write protection is set in the DSCB. 



REPLACE (Replace a 
Password) Statement 



specifies that the password is to allow both read and write access to the data 
set; if a control password is being assigned, read-without-password protection 
is set in the DSCB. 

VOL = device = list 

specifies the direct access volume or volumes that contain the data set to be 
protected. If omitted, the protection status of the data set is not set in the DSCB, 
unless the data set is cataloged. This parameter is not necessary for secondary 
password entries or if the desired protection status is already set in the DSCB. 

DATA = 'user-data' 

specifies that user data is to be included in the password entry. The user data must 
be in single quotes and must not exceed 77 characters. 

The REPLACE statement is used to replace any or all of the following information in 
a password entry: the password name, protection mode (read/write or read-only) of 
the password, and user data. When the control entry for a direct access, online data 
set is replaced, the protection status of the data set is changed in the DSCB if 
necessary; when a secondary entry is replaced, the protection status in the DSCB is 
not changed. 

The format of the REPLACE statement is: 

\ [/abe/] REPLACE DSNAME = name 

' [.PASWORDl = current- password] 

\ [,PASW0RD2 = new-password] 

I [,CPASWORD = control -password] 

\ [.TYPE = code] 

[ [,VOL = device = list] 

\ [,DATA == 'user -data'] 
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where: 

DSNAME = name 

specifies the fully-qualified name of the data set whose password entry is to be 
changed. 

PASWORDl = current-password 

specifies the current password in the entry to be changed. If PASWORDl is 
omitted, the operator is prompted for the current password. 

PASW0RD2 = new-password 

specifies the new password to be assigned to the entry. If the password is not to be 
changed, the current password must also be specified as the new password. The 
password can consist of one- to eight-alphameric characters. If PASW0RD2 is 
omitted, the operator is prompted for a new password. 

CPASWORD = con*ro/-passworc/ 

specifies the control password for the data set whose entry is to be changed. The 
control password must be specified unless the control entry is being changed. If the 
control entry is to be changed, the control password must be specified as 
PASWORDl. 

TYPE = code 

specifies the protection code of the password and, if a control password entry is to 
be changed for a direct access, online data set, specifies the protection status of 
the data set. If this parameter is omitted, the protection is not changed. The values 
that can be specified for code are: 

1 

specifies that the password is to allow both read and write access to the data 
set; if a control password is being changed, read/write protection is set in the 
DSCB. 

2 

specifies that the password is to allow only read access to the data set; if a 
control password is being changed, read/write protection is set in the DSCB. 

3 

specifies that the password is to allow both read and write access to the data 
set; if a control password is being changed, read-without-password protection is 
set in the DSCB. 

VOL = device = list 

specifies the direct access volume or volumes that contain the data set whose 
protection status is to be changed. If omitted, the protection status of the data set 
is not changed in the DSCB, unless the data set is cataloged. This parameter is not 
necessary for secondary password entries or if the protection status of the data set 
is not to be changed. 

DATA = 'user-data' 

specifies that user data is to be included in the password entry. The user data must 
be in single quotes and must not exceed 77 characters. If this parameter is 
omitted, the user data is not changed. 

DELETEP (Delete a The DELETER statement is used to delete an entry in the PASSWORD data set. If 

Password) Statement a control entry is deleted, all the secondary entries for that data set are also deleted. 

If a secondary entry is deleted, only that entry is deleted. When the control entry for a 
direct access, online data set is deleted, the protection status in the DSCB is set to 
indicate that the data set is no longer protected. 

The format of the DELETEP statement is: 

[/abe/] DELETEP DSNAME = name 

[.PASWORDl = current-password] 
[.CPASWORD = control-password] 
[.VOL = device = list] 
where: 

DSNAME = name 

specifies the fully-qualified name of the data set whose password is to be deleted. 

PASWORDl = current-password 

specifies the password to be deleted. 
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LIST (List Information 
from a Password) Statement 



lEHPROGM Examples 



CPASWORD = control-password 

specifies the control password for the data set whose password is to be deleted. 
The control password must be specified unless the control password is to be 
deleted. If the control password is to be deleted, the control password must be 
specified as PASWORDl. 

VOL = dewce = list 

specifies the direct access volume or volumes that contain the data set whose 
password is to be deleted. If omitted, the protection status of the data set is not 
changed in the DSCB, unless the data set is cataloged. This parameter is not 
necessary if a secondary password is to be deleted. 

The LIST statement is used to format and print Information from a password 
entry. 

The format of the LIST statement is: 

r" [/aba/] LIST DSNAME = name" "" - .^,^^.^■..-.~^^•-~»^.~^«~™~.>^.-~".~.~^.--~~-^~~>--: 
| ,PASW0RD1 « current-passworcf 
where: 

DSNAME = name 

specifies the fully-qualified name of the data set whose password entry is to be 
listed. 

PASWORDl = current-password 

specifies the password in the entry to be listed. 

The following examples illustrate some of the uses of lEHPROGM. Table 54 can be 
used as a quick reference guide to lEHPROGM examples. The numbers in the 
"Example" column point to the examples that follow. 



Table 54. lEHPROGM Example Directory 




Operation 


Mountable 
Volumes 


Comments 


Example 


SCRATCH 


2314 Disk 


VTOC is to be scratched. 


1 


SCRATCH 
UNCATLG, 
and DLTX 


2314 Disk 


Two data sets are to be scratched and 
uncataloged. An index structure is to be deleted 
from SYSCTLG. 


2 


RENAME, 
UNCATLG, 
DLTX, and 
CATLG 


2314 Disks 


A data set is to be renamed on two mountable 
devices; the old data set name and index 
structure are to be removed from the catalog. The 
data set is cataloged under its new name. Object 
data set resides on two mountable devices 


3 


UNCATLG 
and DLTX 


2314 Disk 


Three data sets are to be uncataloged; their 
supporting index structures are to be deleted 
from the catalog. 


4 


CONNECT 
and CATLG 


2314 Disk 


Connect system residence volume to a second 
volume. Catalog data sets on second volume. 
SYSCTLG was previously defined on the second 
volume. 


5 


BLDG 


None 


A generation index is to be built. 


6 


BLDG and 
CATLG 


None 


A generation index Is to be built and 
three data sets are to be cataloged. 


7 


RELEASE and 
CONNECT 


None 


Auxiliary control volume is released and 
connected. 


8 


RENAME, 
DELETER, 
and ADD 


2314 Disk 


The object data set exists on one mountable 
device. 


9 


LIST and 
REPLACE 


2314 Disk 


The object data set exists on two mountable 
devices. 


10 


RENAME 


2314 Disk 


Rename a member of a partitioned data set. 


11 
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Note: In the lEHPROGM examples, the EXEC statement and the SYSPRINT DD 
statement can be replaced with the following job control statement: 

// EXEC PROC = MOD 

which invokes the following IBM-supplied cataloged procedure: 

//MOD EXEC PGM = lEHPROGM.REGION = 44K 
//DDSRVDD VOLUME = REF = SYS1.SVCLIB,DISP = OLD 
//SYSPRINT DD SYSOUT = A 

In the following example, data sets are to be scratched from the volume table of 
contents of a mountable volume. Because the system residence volume is not referred 
to, no DDl DD statement is necessary in the job stream. 

The example follows: 

//SCRVTOC JOB 09#550, BROWN 
// EXEC PGM= lEHPROGM 

//SYSPRINT DD SYSOUT=A 



UNIT=23 1 4 , V0LUME=SER=2 31400, DISP=OLD 
* 

VT0C,V0L=23 14=23 1400 



//DD2 DD 
//SYSIN DD 
SCRATCH 
/* 

The SCRATCH statement, used in this example, indicates that all data sets (including 
those beginning with AAAAAA.AAAAAA.AAAAAA.AAAAAA) whose expiration dates 
have expired are to be scratched from the specified volume. 

In this example, two data sets are to be scratched: SETl is to be scratched on volume 
231401, and A.B.C.D.E is to be scratched on volume 231402. Both data sets are to 
be uncataloged, and index structure A.B.C.D is to be deleted from the SYSCTLG data 
set. Because the system residence volume, which resides on a 3330 volume, is 
referred to through use of the UNCATLG and DLTX statements, a DD statement is 
included in the input stream. 

The example follows: 



//SCRDSETS JOB 

// EXEC 

//SYSPRINT DD 

//DDl DD 

//DD2 DD 

//SYSIN DD 

SCRATCH 

UNCATLG 

SCRATCH 

UNCATLG 

DLTX 

DLTX 

DLTX 

DLTX 

/* 

In this example, the name of a data set is to be changed on two mountable volumes. 
The old data set name and index structure are to be removed from the catalog and 
the data set is to be cataloged under its new data set name. 

The example follows: 

//RENAMEDS JOB 09#550, BROWN 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DDl DD V0LUME=SER=1 1 1 1 11 ,UNIT=3330,DISP=OLD 

//DD2 DD UNIT=( 2314, , DEFER ),DISP=OLD, 

// VOLUME=( PRIVATE, SER=( 231 400, 231401 ) ) 



09#550, BROWN 

PGM=IEHPROGM 

SYSOUT=A 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=2314,DISP=OLD,VOLUME=SER=( 231400 ) 

* 

DSNAME=SET1 ,VOL=23 14=23 1401 

DSNAME=SET1 

DSNAME=A.B.C.D.E,VOL=23 14=23 1402 

DSNAME=A.B.C.D.E 

INDEX=A,B.C.D 

INDEX=A.B.C 

INDEX=A.B 

INDEX=A 



//SYSIN 
RENAME 

UNCATLG 

DLTX 

DLTX 

CATLG 

/* 



DD * 

DSNAME=A . B . C , NEWNAME=NEWSET , 
VOL=2314=( 231400,231401 ) 
DSNAME=A.B.C 
INDEX=A.B 
INDEX=A 
DSNAME=NEWSET,VOL=2314=( 231400,231401 ) 



lie 
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lEHPROGM Example 6 



In this example, three data sets— A.B.C.D.E.F.SETl, A.B.C.G.H.SET2, and 
A.B.I.J.K.SET3 — are to be uncataloged and their supporting index structures deleted 
from the catalog. The system residence volume resides on a 2314 volume. 

The example follows: 



//DLTSTRUC JOB 


09#550, BROWN 


// EXEC 


PGM= lEHPROGM 


//SYSPRINT DD 


SYSOUT=A 


//DD1 DD 


UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 


//SYSIN DD 


* 


UNCATLG 


DSNAME=A.B.C.D.E.F.SET1 


UNCATLG 


DSNAME=A . B . C . G . H . SET2 


UNCATLG 


DSNAME=A . B . I . J . K . SET3 


DLTX 


INDEX=A.B.I.J.K 


DLTX 


INDEX=A.B.I.J 


DLTX 


INDEX=A.B.I 


DLTX 


INDEX=A.B.C.G.H 


DLTX 


INDEX=A.B.C.G 


DLTX 


INDEX=A . B . C . D . E . F 


DLTX 


INDEX=A.B.C.D.E 


DLTX 


INDEX=A.B.C.D 


DLTX 


INDEX=A.B.C 


DLTX 


INDEX=A.B 


DLTX 


INDEX=A 



/* 

In this example, the system residence volume, which resides on a 3330 volume, is to 
be connected to a second volume. Any subsequent index search for index level X, Y, 
or Z will be carried to the second volume. 

The example follows: 

//CONNECT JOB 09#550, BROWN 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330,VOLUME=SER=1 111 1 1 ,DISP=OLD 

//DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 

//SYSIN DD . * 

CONNECT INDEX=X,VOL=23 14=23 1400 

CONNECT INDEX=Y,VOL=23 14=23 1400 

CONNECT INDEX=Z,VOL=23 14=23 1400 

CATLG DSNAME=X.BB.CCC,VOL=23 14=23 1401 ,CVOL=23 14=23 1400 

GATLG DSNAME=Y. BB.CC,VOL=23 14=231 40 1 ,CVOL=23 14=23 1400 

CATLG DSNAME=Z.BB. XT, VOL=23 14=23 1401 ,CVOL=23 14=23 1 400 
/* 

The control statements are discussed below: 

• The CONNECT statements identify the second volume. The specified index names, 
along with the volume identification, are placed on the system residence volume. 

• The CATLG statements catalog three data sets (X.BB.CCC, Y.BB.CC, and Z.BB.XT) 
on the second volume. Because the volumes are connected before the catalog 
operations are performed, the CVOL parameters are not required in the CATLG 
statements; they are included to bypass the index search on the system residence 
volume. 

In this example, a generation index is to be built in the catalog. The system residence 
volume resides on a 3330 volume. 

The example follows: 

//BLDGDGIX JOB 09#550, BROWN 
// EXEC PGM= lEHPROGM 

//SYSPRINT DD 
//DD1 DD 
//SYSIN DD 
BLDG 

/* 

The BLDG statement specifies the generation data group A.B.C and makes provision 

for ten entries in the index. All entries are to be removed from the index when it 

overflows. 



SYSOUT=A 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

* 

INDEX=A . B . C , ENTRIES= 1 , EMPTY 
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JOB 09#550, BROWN 
EXEC PGM= lEHPROGM 



In this example, a generation index is to be built and three data sets are to be 
cataloged in the index. The system residence volume resides on a 3330 volume. 

The example follows: 

//CTLGDG 

// 

//SYSPRINT DD 

//DD1 DD 

//SYSIN DD 

BLDG 

CATLG 

CATLG 

CATLG 



SYSOUT=A 

UNIT=3330,VOLUME=SER=1 11111 ,DISP=OLD 

* 

INDEX=A. B. C, ENTRIES=20 , EMPTY 
DSNAME=A.B.C.G0001VOO,VOL=23 14=23 1400 
DSNAME=A. B . C . G0002V00 , VOL=23 1 4=23 1 400 
DSNAME=A.B.C.G0003V00,VOL=23 14=23 1400 



/* 

Figure 63 shows the index structure after the three generation data sets are 
cataloged. 



t 

B 
t 
C G0003V00 G0002V00 GOOOIVOO 

(latest. (latest -1) (latest -2) 

generation) 

Figure 63. index Structure After Generation Data Sets Are Cataloged 
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In this example, the RELEASE and CONNECT statements are used to disconnect the 
control volume, 231400, from the system residence catalog for the high level index A 
and to reconnect that same control volume for that index. This technique is necessary 
only if the auxiliary control volume was connected before Release 17. The system 
residence volume resides on a 2314 volume. 



09#550, BROWN 

PGM=IEHPROGM 

SYSOUT=A 

UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 

* 

INDEX=A 

INDEX=A,VOL=23 14=23 1400 



The example follows: 

//RECONCT JOB 
// EXEC 

//SYSPRINT DD 
//DD1 DD 
//SYSIN DD 

RELEASE 

CONNECT 
/* 

In this example, a data set is to be renamed. The data set passwords assigned to the 
old data set name are to be deleted. Then two passwords are to be assigned to the 
new data set name. 

Note: If the data set is not cataloged, a message indicating that the LOCATE macro 
instruction failed is issued. The return code is 8. 

The example follows: 

//ADDPASS JOB 09#550, BROWN 

EXEC PGM=IEHPROGM , PARM= ' NOPRINT ' 
//SYSPRINT DD SYSOUT=A 

//DD1 DD VOLUME=( PRIVATE, SER=231 400 ),DISP=OLD, 
// UNIT=( 2314, , DEFER) 
//SYSIN DD * 
RENAME DSNAME=OLD , VOL=23 1 4=23 1 400 , NEWNAME=NEW 
DELETEP DSNAME=0LD,PASW0RD1=KEY 
ADD DSNAME=NEW,PASW0RD2=KEY,TYPE=1 , UC 

DAT A= ' SECONDARY IS READ' 
ADD DSNAME=NEW,PASWORD2=READ,CPASWORD=KEY,TYPE=2, IIC 

DATA=' ASSIGNED TO J. DOE' 
/* 

The control statements are discussed below: 

• DELETEP specifies that the entry for the password KEY is to be deleted. Because 
KEY is a control password in this example, all the password entries for the data set 
name are deleted. The VOL parameter is not needed because the protection status 
of the data set as set in the DSCB is not to be changed; read/write protection is 
presently set in the DSCB, and read/write protection is desired when the 
passwords are reassigned under the new data set name. 
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• The ADD statements specify that entries are to be added for passwords KEY and 
READ. KEY becomes the control password and allows both read and write access to 
the data set. READ becomes a secondary password and allows only read access to 
the data set. The VOL parameter is not needed, because the protection status of 
the data set is still set in the DSCB. 

Note: The operator is required to supply a password to rename the old data set. 

In this example, information from a password entry is to be listed. Then the protection 
mode of the password, the protection status of the data set, and the user data are to 
be changed. 

The example follows: 

//REPLPASS JOB 09# 550, BROWN 

EXEC PGM=IEHPROGM,PARM='NOPRINT' 
//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330,VOLUME=SER=1111 11 ,DISP=OLD 
//DD2 DD VOLUME=( PRIVATE, SER=( 231400,231401 ) ), 
// UNIT=( 2314, , DEFER ),DISP=OLD 
//SYSIN 

LIST 
REPLACE 



DD 



DSNAME=A . B . C , PASWORD 1 =ABLE 
DSNAME=A . B . C , PASWORD 1 =ABLE , 

PASW0RD2=ABLE , TYPE=3 , 

VOL=2314=(231400, 231401 ), 

DATA='NO SECONDARIES; ASSIGNED TO DEPT 31' 



??C 

nc 
nc 



/* 

The control statements are discussed below: 

• LIST specifies that the access counter, protection mode, and user data from the 
entry for password ABLE are to be listed. Listing the entry permits the content of 
the access counter to be recorded before the counter is reset to zero by the 
REPLACE statement. 

• REPLACE specifies that the protection mode of password ABLE is to be changed to 
allow both read and write access and that the protection status of the data set is to 
be changed to write-only protection. The VOL parameter is required because the 
protection status of the data set is being changed and the data set, in this example, 
is not cataloged. Because this is a control password, the CPASWORD parameter is 
not required. 

In this example, a member of a partitioned data set is to be renamed. 

The example follows: 

//REN 

// 

//DD1 
//SYSIN 
RENAME 
/* 

The control statements are discussed below: 



JOB 09#550, BROWN 

EXEC PGM=IEHPROGM 

DD VOL=SER=23141 1 ,DISP=OLD, UNIT=231 4 

DD * 

VOL=23 1 4=23 1 411, DSNA]yiE=DATASET , NEWNAME=BC , MEMBER=ABC 



DDl DD defines a permanently mounted volume. 

SYSIN DD defines the input data set, which immediately follows in the input stream. 

RENAME specifies that member ABC in the partitioned data set DATASET, which 
resides on a 2314 volume, is to be renamed BC. 
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IFHSTATR is a system utility used to select, format, and write information from type 
21 (error statistics by volume) records when System Management Facilities (SMF) has 
been system generated into the system. (See "Introduction" for general system utility 
information.) 

Figure 64 shows the format of the type 21 record. 



4 


Bytes of Record Descriptor Word 





System 
Indicator 


Record Type 


Time of Day 


4 


Time of Day (continued) 


Current Date 


8 


Current Date (continued) 


System 
Identification 


12 


System Identifier 


Lengtfi of rest of record 
includinq this field 


16 


Volume Serial Number 


20 


Volume Serial No. (cont.) 


22 Cfiannel/Unit Address 


24 


UCB Type 


28 


Temporary Read 
Errors 


Temporary Write 
Errors 


Start l/O's 


32 


Permanent Read 
Errors 


Permanent Write 
Errors 


Noise Blocks 


Erase Gaps 


36 


Erase Gaps 
(continued) 


Cleaner Actions 


Tape Density 


40 


Block Size 


Reserved 



Figure 64. Type 21 (ESV) Record Format 



Input and Output 



Error statistics by volume (ESV) records should be retrieved from the IFASMFDP tape 
or from SYSl.MAN (on tape). ESV can also be retrieved directly from SYSl.MANX or 
SYSl.MANY (on a direct access storage device); however, IFHSTATR does not clear 
the SYSl.MANX (or SYSl.MANY) data set and make it available for additional 
records. 

IFHSTATR uses as input type 21 records, which contain information about errors on 
magnetic tape. IFHSTATR processes only type 21 records; if none are found, a 
message is written to the output data set. 

IFHSTATR produces as output an output data set, which contains information selected 
from type 21 records. The output takes the form of 121 -byte unblocked records, with 
an ASA control character in the first byte of each record. 

Figure 65 shows a sample of printed output from IFHSTATR. 




VOLUME 

SERIAL .DATE 

001021 69/309 

001022 69/309 
000595 69/309 



MOD TIME CHANNEL TEMP TEMP PERM PERM NOISE ERASE 
NO OF DAY / UNIT READ WRITE READ WRITE BLOCKS GAPS 



AO 15:55:07 
40 15:56:02 
50 15:56:20 



181 
184 
283 



m 




CLEANER 
ACTIONS 



USAGE 
(SIO's) 



TAPE 
DENSITY 



BLOCK 
LENGTH 



Figure 65. Sample Output from IFHSTATR 



Control 



IFHSTATR is controlled by job control statements. Utility control statements are not 
used. 
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IFHSTATR Example 



Table 55 shows the job control statements necessary for using IFHSTATR. 

Table 55. IFHSTATR Job Control Statements 

Statement Use 

JOB Initiates the job. 

EXEC Specifies the program name (PGM = IFHSTATR). 

SYSUTl DD Defines the input data set and the device on which it resides. The DSNAME, 



SYSUT2 DD 



UNIT, VOLUME, LABEL, DCB, and DISP parameters should be included. 
Defines the sequential data set on which the output is to be written. 



The minimum region size that can be specified for the execution of IFHSTATR is 4K. 

The output data set can reside on any output device supported by BSAM. 

Note: The LRECL and BLKSIZE parameters are not specified by IFHSTATR. This 
information is taken from the DCB parameter on the SYSUTl DD statement or from 
the tape label. 

This example shows the JCL needed to produce a report. 

The example follows: 

// JOB 

// EXEC PGM= IFHSTATR 

//SYSUTl DD UNIT=2400,DSNAME=SYS1 .MAN,LABEL=( ,SL), 

// VOLUME=SER=VOLID,DISP=OLD 

//SYSUT2 DD SYSOUT=A 

/* 
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Appendix A: Exit Routine Linkage 



Linking to an 
Exit Routine 



Label Processing 
Routine Parameters 



Utility programs can be linked to user-supplied exit routines for additional processing. 

Linking to an exit routine from a utility program is accomplished in one of the 
following ways: 

• If the exit routine is for label processing or totaling, or if the exit routine is specified 
in the lEBTCRIN program by OUTREC or ERROR, linkage is performed by the BALR 
instruction. 

• In all other cases, linkage is performed by using the LINK macro instruction. 

The LINK macro instruction contains the symbolic name of the entry point of an exit 
routine and, if required, a list of parameters. 

For further information on the use of the LINK macro instruction, see OS Supervisor 
Services Guide, GC28-6646, and OS Supervisor & Data Management Macro 
Instructions, GC28-6647. 

At the time of the linkage operation: 

• General register 1 contains the starting address of the parameter list, or contains 
zero to indicate end-of-file on the input data set for the lEBTCRIN OUTREC or 
ERROR exits. 

• General register 13 contains the address of the register save area. This save area 
must not be used by user label processing routines or by the lEBGENER 
input/output error exit routines. See "Appendix E: Processing User Labels." 

• General register 14 contains the address of the return point in the utility program. 

• General register 15 contains the address of the entry point to the exit routine. 

Registers 1 through 14 must be restored before control is returned to the utility 
program. 

The exit routine must be contained in either the job library or the link library. 

The parameter lists passed to label processing routines and parameter lists passed to 
nonlabel processing routines are described in the topics that follow. 

The parameters passed to a user's label processing routine are addresses of the 
80-byte label buffer, the DCB being processed, the status information if an 
uncorrectable input/output error occurs, and the totaling area. 

The 80-byte label buffer contains an image of the user label when ah input label is 
being processed. When an output label is being processed, the buffer contains no 
significant information at entry to the user's label processing routine. When the utility 
program has been requested to generate labels, the label processing routine 
constructs a label in the label buffer. 

If standard user labels (SUL) are specified on the DD statement for a data set, but the 
data set has no user labels, the system still takes the specified exits to the 
appropriate user's routine. In such a case, the user's input label processing routine is 
entered with the buffer address parameter set to zero. 

The format and content of the DCB are presented in OS Supervisor & Data 
Management Macro Instructions, GC28-6647. 

Bit of flag 1 in the DCB-address parameter is set to a value of except when: 

• Volume trailer or header labels are being processed at volume switch time. 

• The trailer labels of a MOD data set are being processed (when the data set is 
opened). 

If an uncorrectable input/output error occurs while reading or writing a user label, the 
appropriate label processing routine is entered with bit of flag 2 in the status 
information address parameter set on. The low order three bytes of this parameter 
contain the address of standard status information as supplied for SYNAD routines. 
(The SYNAD routine is not entered.) 
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Nonlabel Processing 
Routine Parameters 



Returning from 
an Exit Routine 



Table 56 shows the program from which exits can be taken to nonlabel processing 
routines, the names of the exits, and the parameters available for each exit routine. 

Table 56. Parameter Lists for Nonlabel Processing Exit Routines 

Program Exit Parameters 

lEBGENER KEY Address at which key is to be placed (record follows key); 

address of DCB. 
DATA Address of SYSUTl record; address of DCB. 

lOERROR Address of DECB; cause of the error and address of DCB 

(address In lower order three bytes and cause of error In high 

order byte). 

lEBDG OUTREC Address of output record. 

lEBCOMPR ERROR Address of DCB for SYSUTl ; address of DCB for SYSUT2.1 

PRECOMP Address of SYSUTl record; length of SYSUTl record, address of 

SYSUT2 record; length of SYSUT2 record. 

lEBPTPCH INREC Address of input record; length of the input record. 

OUTREC Address of output record; length of output record. 

lEBTCRIN ERROR Address of the error record; address of a full word which 

contains the record length. 
OUTREC Address of the normal record; address of a full word which 

contains the record length. 

1 The lOBAD pointer in the DCB points to a location that contains the address of the corresponding 
data event control block (DECB) for these records. The format of the DECB is illustrated as part 
of the BSAM READ macro instruction in OS Supervisor & Data (Management IMacro Instructions, 
GC28-6647. 

An exit routine returns control to the utility program by means of the macro instruction 
in the exit routine. 

The format of the RETURN macro instruction is: 

: [/aba/] RETURN [(rJ,r2)] 

,RC= {n } 

i {15} 

where: 

(rl,r2) 

specifies the range of registers to be reloaded by the utility program from the 
register save area. If this parameter is omitted, the registers are considered 
properly restored by the exit routine. 

RC = 

specifies a return code in register 15. If RC is omitted, register 15 is loaded as 
specified by (rl,r2). These values can be coded: 



15 



specifies a return code to be placed in the 12 low-order bits of register 15. 

specifies that general register 15 already contains a valid return code. 

The user's label processing routine must return a code in register 15 as shown in 
Table 57 unless: 

• The buffer address was set to zero before entry to the label processing routine. In 
this case, the system resumes normal processing regardless of the return code. 

• The user's label processing routine was entered after an uncorrectable output error 
occurred. In this case the system attempts to resume normal processing. 

Table 57 shows the return codes that can be issued to utility programs by user exit 
routines. Slightly different return codes are used for the UPDATE = INPLACE option of 
the lEBUPDTE program. See the discussion of UPDATE = INPLACE in the chapter 
"lEBUPDTE Program." 



280 Utilities (Release 21.7) 



Table 57. Return Codes Issued by User Exit Routines 



Type of Exit 

Input Header or 
Trailer Label 



Output Header or 
Trailer Label 



Totaling Exits 



All other exits 
(except lEBTCRIN's 
ERROR and OUTREC 
and lEBPTPCH's 
exit OUTREC) 



ERROR 



I OUTREC (lEBTCRIN) 
4 
16 
OUTREC (lEBPTPCH) 4 



Return 

Code Action 

The system resumes normal processing. If there are 

more labels in the label group, they are ignored. 

4 The next user label is read into the label buffer area and 

control is returned to the user's routine. If there are no 
more labels, normal processing is resumed. 

16 The utility program is terminated on request of the user 

routine. 

The system resumes normal processing. No label is 

No label is written from the label buffer area. 

4 The user label is written from the label buffer area. The 

system then resumes normal processing. 

8 The user label is written from the label buffer area. If fewer 

than eight labels have been created, the user's routine again 
receives control so that it can create another user label. If 
eight labels have been created, the system resumes normal 
processing. 

16 The utility program is terminated on request of the user 

routine. 

Processing continues, but no further exits are taken. 

4 Normal operation continues. 

8 Processing ceases, except for EOD processing on output 

data set (user label processing). 

16 Utility program is terminated. 

0-11 Return code is compared to highest previous return code; 

(Set to the higher is saved and the other discarded. At the normal 

next end of job, the highest return code is passed to the 

multiple calling processor, 
of four) 

12 or 16 Utility program is terminated and this return code is passed 

to the calling processor. 

Record is not placed in the error data set. Processing 

continues with the next record. 

4 Record is placed in the error data set (SYSUT3). 

8 Record is not placed in error data set but is processed as a 

valid record (sent to OUTREC and SYSUT2 if specified). 
lEBTCRIN removes the EDW from an edited MTDI record 
before processing continues. 

16 Utility program is terminated. 

Record is not placed in normal output data set. 

Record is placed in normal output data set (SYSUT2). 

Utility program is terminated. 

Record is not placed in output data set. The return code is 
not passed to the calling processor. 

12 or 16 Utility program is terminated and this return code is passed 

to the calling processor. 

Any other Record is placed in the output data set. 

Number The return code is not passed to the calling 

processor. 



Further information on the use of the RETURN macro instruction is contained in OS 
Data Managennent Services Guide, GC26-3746, and OS Supervisor & Data Management 
Macro Instructions, GC28-6647. 

For a list of return codes issued by lEBTCRIN at job termination, see the "lEBTCRIN 
Program" chapter of this publication. 
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Appendix B: Invoking Utility Programs from a Problem Program 



utility programs can be invoked by a problem program tlirough the use of the ATTACH 
or LINK macro instruction. In addition, lEBTCRIN can be invoked through the use of 
the LOAD or CALL macro instruction. 

The problem program must supply the following to the utility program: 

• The information usually specified in the PARM parameter of the EXEC statement. 

• The ddnames of the data sets to be used during processing by the utility program. 

Note: When lEHMOVE, lEHPROGM, or lEHLIST is dynamically invoked in a job step 
containing a program other than one of these three, the DD statements defining 
mountable devices for the lEHMOVE, lEHPROGM, or lEHLIST program must be 
included in the job stream prior to DD statements defining data sets required by the 
other program. 

LINK or ATTACH The LINK or ATTACH macro instruction can be used to invoke a utility program 

Macro Instruction from a problem program. 

The format of the LINK or ATTACH macro instruction is: 

>■'':• eXriame] -^x^ LINK' S'^ 

where: 

EP = progname 

specifies the symbolic name of the utility program. 

PARAM = 

specifies, as a sublist, address parameters to be passed from the problem program 
to the utility program. These values can be coded: 

optionaddr 

specifies the address of an option list, which is usually specified in the PARM 
parameter of the EXEC statement. This address must be written for all utility 
programs. 

ddnameaddr 

specifies the address of a list of alternate ddnames for the data sets used during 
utility program processing. If standard ddnames are used and this is not the last 
parameter in the list, it should point to a halfword of zeros. If it is the last 
parameter, it may be omitted. 

hdingaddr 

specifies the address of a six-byte list, HDNGLIST, which contains an EBCDIC 
page count for the output device. If hdingaddr is omitted, the page number 
defaults to 1. 

VL=1 

specifies that the sign bit of the last fullword of the address parameter list is to be 
set to 1. 

Figure 66 shows these lists as they exist in the user's DC area. Note that the symbolic 
starting addresses for OPTLIST and DDNMELST fall on halfword boundaries. Note also 
the alternative ddnames INSTREAM, INPUTSET, and WHICHPTR. 

The PARAM parameter of the LINK macro instruction in the calling program provides 
the utility program with the symbolic addresses of the parameter lists shown in Figure 
66, as follows: 

• The option list, OPTLIST, which includes the number of bytes in the list 
(hexadecimal 08) and the NOVERIFY option. 

• The alternate ddname list, DDNMELST, which includes the number of bytes in the 
list (hexadecimal 48) and alternative names for the SYSIN, SYSUTl, and SYSUT2 
data sets. 

• The heading list, HDNGLIST, which includes the number of bytes in the list 
(hexadecimal 04) and indicates the starting page number (shown as 10) for 
printing operations controlled through the SYSPRINT data set. 
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LOAD Macro Instruction 
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Figure 66. Typical Parameter Lists 



The option list, OPTLIST, must begin on a halfword boundary that is not also a fullword 
boundary. The two high order bytes contain a count of the number of bytes in the 
remainder of the list. (For all programs except lEHMOVE, lEHPROGM, lEHINITT, 
lEBISAM, and lEBUPDTE, the count must be zero.) OPTLIST is free form with fields 
separated by commas. No blanks or zeros should appear in the list. 

The ddname list, DDNMELST, must begin on a halfword boundary that is not also a 
fullword boundary. The two high order bytes contain a count of the number of bytes in 
the remainder of the list. Each name of fewer than eight bytes must be left aligned and 
padded with blanks. If an alternate ddname is omitted from the list, the standard name 
is assumed. If the name is omitted within the list, the eight-byte entry must contain 
binary zeros. Names can be omitted from the end by merely shortening the list. Table 
58 shows the sequence of the eight-byte entries in the ddname list pointed to by 
ddnameaddr. 

The first two bytes of HDNGLIST contain the length in bytes of the heading list. The 
remaining four bytes contain a page number that the utility program is to place on the 
first page of printed output. 

lEBTCRIN can be invoked through use of the LOAD macro instruction. 

The LOAD macro instruction causes the control program to bring the load module 
containing the specified entry point into main storage unless a copy is already there. 
Control is not passed to the load module. 

Table 58. Sequence of DDNMELST Entries 

Entry Standard Name 



1 


00000000 


2 


00000000 


3 


00000000 


4 


00000000 


5 


SYSIN 


6 


SYSPRINT 


7 


00000000 


8 


SYSUTl 


9 


SYSUT2 


10 


SYSUT3 


11 


SYSUT4 



The format of the LOAD macro instruction is: 

[name] LOAD {EP = lEBTCRIN } 

{EPLOC = address of name } 

where: 

EP = lEBTCRIN 

is the entry point name of the program to be brought into main storage. 

EPLOC = address of name 

is the main storage address of the entry point name described above. 
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CALL Macro Instruction The CALL macro instruction can be used to pass control to lEBTCRIN after lEBTCRIN 

has been loaded into main storage. 

Control can be passed to lEBTCRIN via a CALL macro instruction or via a branch and 
link instruction. If the branch and link instruction is used, register 1 must be loaded 
with the address of a parameter list of full words as described under "LINK or 
ATTACH Macro Instruction." The last parameter list address must contain X'80' in 
byte 1 to indicate the last parameter in the list. 

The format of the CALL macro instruction is: 

\ [name]CALL IEBTCRIN(,opt/onarif<r[,cfdfj3m^addr][,hcf/ngaddr]),VL 



where: 

lEBTCRIN 

is the name of the entry point to be given control; the name is used in the macro 
instruction as the operand of a V-type address constant. 

optionaddr 

specifies the address of an option list, OPTLIST, usually specified in the PARM 
parameter of the EXEC statement. This address must be written for all utility 
programs. 

ddnameaddr 

specifies the address of a list of alternate ddnames, DDNMELST, for the data sets 
used during utility program processing. If standard ddnames are used and this is 
not the last parameter in the list it should point to a halfword of zeros. If it is the 
last parameter, it may be omitted. 

hdingaddr 

specifies the address of a six-byte list containing an EBCDIC page count for the 
output device. 

VL 

specifies that the high order bit of the last address parameter in the macro 
expansion is to be set to 1. 

The option list, OPTLIST, must begin on a halfword boundary that is not also a fullword 
boundary. The two high order bytes contain a count of the number of bytes in the 
remainder of the list. (For all programs except lEHMOVE, lEHPROGM, lEHINITT, and 
lEBISAM, the count must be zero.) The option list is free form with fields separated by 
commas. No blanks or zeros should appear in the list. 

The ddname list, DDNMELST, must begin on a halfword boundary that is not also a 
fullword boundary. The two high order bytes contain a count of the number of bytes in 
the remainder of the list. Each name of fewer than eight bytes must be left aligned and 
padded with blanks. If an alternate ddname is omitted from the list, the standard name 
is assumed. If the name is omitted within the list, the eight-byte entry must contain 
binary zeros. Names can be omitted from the end by merely shortening the list. The 
sequence of the eight- byte entries in the ddname list pointed to by ddnameaddr is 
shown earlier in Table 58. 

The first two bytes of the heading list, HDNGLIST, contain the length in bytes of the 
heading list. The remaining four bytes contain a page number that the utility program 
is to place on the first page of printed output. 
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Appendix C: DD Statements for Defining Mountabie Devices 



DD Statement Examples 
DD Example 1 



DD Example 2 



DD Example 3 



When defining mountabie devices to be used by system utility programs lEHPROGM, 
lEHMOVE, lEHLIST, or lEHDASDR, the user must consider the implications of the DD 
statements he uses to define those devices. 

DD statement parameters must ensure that no one else has access to either the 
volume or the data set. Caution should be used when altering volumes that are 
permanently resident or reserved (for example, volumes containing system data sets, 
non-demountable volumes, and volumes reserved through the PRESRES option). 

Under normal conditions, a mountabie device should not be shared with another job 
step; that is, if a utility program is used to update a volume on a mountabie device, 
the volume being updated must remain mounted until the operation is completed. 

Following are ways to ensure that mountabie devices are not shared: 

• Specify DEFER in a DD statement defining a mountabie device. 

• Specify unit affinity on a second DD statement defining a mountabie device. 

• Specify a volume count in the VOLUME parameter of a DD statement that is greater 
than the number of mountabie devices to be allocated. 

• Specify PRIVATE in a DD statement defining a mountabie device. 

For a detailed discussion, see OS JCL Reference, GC28-6704. 

In the following examples of DD statements, an IBM 2314 Disk Storage Device is 
indicated as the mountabie device. Alternative parameters are stacked. 

This DD statement makes a specific request for a private, nonsharable volume or 
volumes to be mounted on a single 2314 device. 

The example follows: 

//DD1 DD UNIT=( 2314, , DEFER ),DISP=( , KEEP), 
// VOLUME=( PRIVATE , SER=( 1 23456 ) ) 

A utility program causes a mount message to be issued for a specific volume when the 
volume is required for processing by the program. The user should supply the 
operator with the clearly marked volume or volumes to be mounted during the job 
step. 

This DD statement ensures that the volume integrity of a mountabie volume is 
maintained. If only one volume is to be processed, it is mounted at the start of the job 
step and dismounted at the end of the step. If additional volumes are processed, they 
are mounted and dismounted when needed by the utility program. The last volume to 
be processed is dismounted at the end of the job step. 

This DD statement makes a request for a private, nonsharable volume. 

The example follows: 

//DD2 DD UNIT=( 2314, , DEFER ),VOLUME=PRIVATE,DISP=(NEW,KEEP) 

The results of this statement are identical to those shown in DD Example 1. 

If a specific unit is requested and the volume serial number is not given in the DD 
statement, the user must be certain that either: (1) the desired volume is already 
mounted on that unit or (2) a volume is not mounted, causing the system to issue a 
mount message. 

Note: This statement can be used only if the user is certain that a removable volume, 
rather than a fixed volume, will be allocated by the scheduler. If there is any chance 
that a fixed volume will be allocated, this statement must not be used. 

This DD statement makes a specific request for a private, sharable volume to be 
mounted on a 2314 device. 

The example follows: 

//DD1 DD UNIT=2314,VOLUME=( PRIVATE, SER=( 121212 ) ),DISP=OLD 

This DD statement does not ensure that volume integrity is maintained. It should be 
used with extreme caution. A concurrently running job step might make a specific 
request for the volume, use the volume, and demount it. 
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DD Example 4 



DD Example 5 



This DD statement makes a specific request for a public, nonsharable volume to be 
mounted on a 2314 device. 

The example follows: 

//DD3 DD UNIT=( 2314, , DEFER ),VOLUME=SER=7890 12, DISP=( , OLD) 

If the volume is already mounted, it is used. The volume remains mounted at the end 
of the job step, and is not demounted until another job step requires the device on 
which the volume is mounted. 

This DD statement ensures that volume Integrity is maintained between jobs; two or 
more such statements in a single job can allocate the same device. 

This DD statement makes a specific request for a public, sharable volume to be 
mounted on a 2314 device. 

The example follows: 

//DD1 DD UNIT=2314,VOLUME=SER=654321 ,DISP=OLD 

If the volume is already mounted, it is used. The volume remains mounted at the end 
of the job step, and is not demounted until another job step requires the device on 
which the volume is mounted. (This DD statement can also be used to define 
permanently resident devices.) 

This DD statement does not ensure that the volume integrity of a mountable volume is 
maintained. It should be used with extreme caution because there is the possibility 
that a job step running concurrently might use the device. 
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A generation data group is a group of related cataloged data sets. The manner in 
which these data sets are cataloged is what makes them a generation data group. 
Within a generation data group, the generations can have like or unlike DCB attributes 
and data set organizations. If the attributes and organizations of all generations in a 
group are identical, the generations can be retrieved together as a single data set. 
Each data set within a generation data group is called a generation data set. 
Generation data sets are sometimes called generations. 

There are advantages to grouping related data sets. Because the catalog management 
routines can refer to the information in a special index — called a generation index — in 
the catalog: 

• All of the data sets in the group can be referred to by a common name. 

• The operating system is able to keep the generations in chronological order. 

• Outdated or obsolete generations can be automatically deleted by the operating 
system. 

The management of a generation data group depends upon the fact that generation 
data sets have sequentially ordered names — absolute and relative names — that 
represent their age. The absolute generation name is the representation used by the 
catalog management routines in the catalog. Older data sets have smaller absolute 
numbers. The relative name is a signed integer used to refer to the latest (0), next to 
the latest (-1), etc. generation. The relative number can also be used to catalog a new 
generation (+1). 

Absolute Generation An absolute generation and version number is used to identify a specific generation 

and Version Numbers of a generation data group. The generation and version numbers are in the form 

GxxxxVyy, where xxxx is an unsigned four-digit decimal generation number and yy is 
an unsigned two-digit decimal version number. For example: 

• A.B.C.GOOOOVOO is generation data set zero, version zero in the generation data 
group A.B.C. 

• A.B.C.GOOOIVOO is generation data set one, version zero in generation data group 
A.B.C. 

• A.B.C.G0009V01 is generation data set nine, version one in generation data group 
A.B.C. 

The number of new generations and versions is limited by the number of digits in the 
absolute generation name, that is, 9999 for generations and 99 for versions. 

The generation number is automatically maintained by the system. The number of 
generations kept depends on the size of the generation index. For example, if the size 
of the index allows ten entries, the ten latest generations may be maintained in the 
index. 

The version number allows you to perform normal data set operations without 
disrupting the management of the generation data group. For example, if you want to 
update the second generation in a three-generation index, replace generation two, 
version zero, with generation two, version one. Only one version is kept per 
generation. 

A generation can be cataloged using either absolute or relative numbers. When a 
generation is cataloged, a generation and version number is placed as a low level 
entry in the generation index. In order to catalog a version number other than VOO, 
you must use an absolute generation and version number. 

Figure 67 shows how the index looks when three generations are cataloged. Note that 
the generation index is a pushdown list, which allows you to use relative generation 
numbers when cataloging or retrieving a generation. 

Note: A new version of a specific generation can be cataloged automatically by 
specifying the old generation number along with a new version number. For example, if 
generation A.B.C.G0005V00 is cataloged in the index and you now create and catalog 
A.B.C.G0005V01, the new entry is cataloged in the index location previously occupied 
by A.B.C.G0005V00. This process removes the old entry from the catalog but does 
not scratch the old version. To scratch the old version and make its space available 
for reallocation, a DD card, describing the data set to be deleted, with 
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Relative Generation Numbers 



Building a Generation 
Index 




Figure 67. Generation Index — Three Entries 



DISP = (OLD.DELETE) should be included at the time the data set is to be replaced by 
the new version. 

As an alternative to using absolute generation and version numbers when cataloging 
or referring to a generation, you can use a relative generation number. To specify a 
relative number, use the generation data group name followed by a negative integer, a 
positive integer, or a zero, enclosed in parentheses. For example, A.B.C(-l), 
A.B.C(+1), or A.B.C(O). 

The value of the specified integer tells the operating system what generation number 
to assign to a new generation, or it tells the system the location (in the generation 
index) of an entry representing a previously cataloged generation. 

When you use a relative generation number to catalog a generation, the operating 
system assigns an absolute generation number and a version number of VOO to 
represent that generation. The absolute generation number assigned depends on the 
number last assigned and the value of the relative generation number that you are 
now specifying. For example, if in a previous job generation A.B.C.G0005V00 was the 
last generation cataloged and you specify A.B.C(+1), the generation now cataloged is 
assigned the number G0006V00. Though any positive relative generation number can 
be used, a number greater than 1 may cause absolute generation numbers to be 
skipped. 

When you use a relative generation number to refer to a generation that was 
cataloged in a previous job, the relative number has the following meaning: 

• A.B.C(O) refers to the latest existing cataloged entry. 

• A.B.C(-l) refers to the next to latest entry, etc. 
When cataloging is requested: 

• A relative number refers to the same generation throughout a job. 

• A job step that terminates abnormally may be deferred for a later step restart. If 
the step cataloged a generation data set via JCL, you must change all relative 
generation numbers in the succeeding steps via JCL before resubmitting the job. 

For example, if the succeeding steps contained the relative generation numbers: 

• A.B.C(+1), which refers to the entry cataloged in the terminated job step. 

• A.B.C(O), which refers to the next to latest entry. 

• A.B.C(-l), which refers to the third latest entry, etc. 

You must change them as follows before the step can be restarted: A.B.C(O), 
A.B.C(-l), A.B.C(-2), etc. 

Note: New nonspecific generation data group requests are cataloged with a volume 
serial number of X'FF4040404040' if they are not opened, so that data set integrity is 
maintained and an incorrect generation is not retrieved. 

Figure 68 shows how an index looks after three generations — A.B.C(+1), A.B.C(+1), 
and A.B.C(+2) — have been cataloged in three separate jobs. The first generation is 
assigned the generation number GOOOIVOO; the second, G0002V00; the third, 
G0004V00. 

A generation data group is managed via the information found in a generation index. 
To build a generation index, use the BLDG function of the lEHPROGM utility program. 
The BLDG function builds the index, providing lower level entries for as many 
generations (up to 255) as needed in a generation data group. The BLDG function 
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Figure 68. Relative Positioning — ^Three Entries in the Catalog 

also indicates how older or obsolete generations are to be handled when the index is 
full. For example, when the index is full, you may wish to empty it, scratch existing 
generations, and begin cataloging a new series of generations. 

Note: An alias cannot be assigned to the highest level of a generation index. 

Figure 69 shows a generation index. When the index was built, provision was made for 
the subsequent cataloging of ten generations. 

After the index is built, a generation can be cataloged by its generation data group 
name and either an absolute generation and version number or a relative generation 
number. 

Examples showing how to build a generation index included in "Cataloging a 
Generation" in this appendix. 



Creating a New Generation 




A.B.C. 
GOOOOVOO 



Figure 69. Generation Index 



To create a new generation data set: 

• Allocate the generation. 

• Catalog the generation. 
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Allocating a Generation 



Cataloging a Generation 

Using JCL Procedures 
to Catalog a Generatior) 



Usmg lEHPROGM to 
Catalog a Generation 



Creating an ISAM Data 
Set as Part of a 
Generation Data Group 



To take full advantage of the facilities of the system, the allocation can be patterned 
after a previously allocated generation in the same group. This is accomplished by the 
specification /Of DCB attributes for the new generation as described below. 

If you are using absolute generation and version numbers, DCB attributes for a 
generation can be supplied directly in the DCB parameter of the DD statement 
defining the generation to be created and cataloged. 

If you are using relative generation numbers to catalog generations, DCB attributes 
can be supplied either: (1) by creating a model DSCB on the volume on which the 
index resides (the volume containing the SYSCTLG data set) or (2) by referring to a 
cataloged data set for the use of its attributes. Attributes can be supplied before you 
catalog a generation, when you catalog it, or at both times, as follows: 

1. Create a model DSCB on the volume on which your index resides. You can provide 
initial DCB attributes when you create your model; however, you need not provide 
any attributes at this time. Initial or overriding attributes can be supplied when you 
create and catalog a generation. ^ To create a model DSCB, include the following 
DD statement in the job step that builds the index or in any other job step that 
precedes the step in which you create and catalog your generation: 

//name DD DSNAME = datagrpname.DISP = (.KEEP),SPACE = (TRK,(0)), 
// UNIT = yyyy, VOLUME = SER = xxxxxx, 

// DCB = (applicable subparameters) 

The DSNAME is the common name by which each generation is identified; xxxxxx is 
the serial number of the volume containing the catalog. If no DCB subparameters 
are desired initially, you need not code the DCB parameter. 

2. You do not need to create a model DSCB if you can refer to a cataloged data set 
whose attributes are identical to those you desire or to an existing model DSCB for 
which you can supply overriding attributes. A cataloged data set referred to in this 
manner must reside on the same volume as your index. To refer to a cataloged 
data set for the use of its attributes, specify DCB = (dsname) on the DD statement 
that creates and catalogs your generation. To refer to an existing model, specify 
DCB = (modeldscbname, your attributes) on the DD statement that creates and 
catalogs your generation. 

A generation can be cataloged through the use of normal job control language 
procedures or through the use of lEHPROGM. 

Assuming that a generation index has been built and that provisions have been made 
for supplying DCB attributes, a generation is created and cataloged in the same 
manner as any other type of data set. 

When you use relative numbers in job control language procedures, you must include 
the CATLG subparameter in the DD statement defining the new generation. When you 
use absolute generation and version numbers, you need not catalog the new 
generation immediately. 

The CATLG function of lEHPROGM can be used to catalog a generation. Again, the 
prerequisite for cataloging a generation is the existence of a generation index in the 
SYSCTLG data set. 

Note: You must always use an absolute generation and version number to catalog or 
uncatalog a generation using lEHPROGM. (lEHMOVE and lEHLIST also require that 
absolute generation and version numbers be used.) 

To create an indexed sequential data set as part of a generation data group, you 
must: (1) create the indexed sequential data set separately from the generation 
group and (2) use lEHPROGM to put the indexed sequential data set into the 
generation group. 

Use the RENAME function to rename the data set. Then use the CATLG function to 
catalog the data set. For instance, if MASTER is the name of the generation data 
group, and GggggVvv is the absolute generation name, you would code the following: 

RENAME DSNAME = ISAM.VOL = 2314 = SCRTCH.NEWNAME = MASTER.GggggVvv 
CATLG DSNAME = MASTER.GggggVvv, VOL = 2314 = SCRTCH 



1 Only one model DSCB is necessary for any number of generations, if you plan to use only one 
model, do not supply DCB attributes when you create the model. When you subsequently create 
and catalog a generation, include necessary DCB attributes in the DD statement referring to the 
generation. In this manner, any number of generation data groups can refer to the same model. 
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Retrieving a Generation 



Generation Data 
Group Examples 

Generation Example 1 



A generation is retrieved through the use of job control language procedures. Any 
operation that can be applied to a non-generation data set can be applied to a 
generation. For example, a generation can be updated and reentered in the catalog, or 
it can be copied, printed, punched, or used in the creation of new generation or 
non-generation data sets. 

You can retrieve a generation by using either relative generation numbers or absolute 
generation and version numbers. 

Because two or more jobs can compete for the same resource, generation data 
groups should be updated with caution, as follows: 

1. No two jobs running concurrently should refer to the same generation data group. 
As a partial safeguard against this situation, use absolute generation and version 
numbers when cataloging or retrieving a generation in a multiprogramming 
environment. If you use relative numbers, a job running concurrently may update 
the generation index, perhaps cataloging a new generation which you will then 
retrieve in place of the one you wanted. 

2. Even when using absolute generation and version numbers, a job running 
concurrently might catalog a new version of a generation or perhaps delete the 
generation you wished to retrieve. For this reason, some degree of control should 
be maintained over the execution of job steps referring to generation data groups. 

The following examples show some of the ways in which generations can be created 
and cataloged or retrieved and used as source data in the creation of new generation 
or non-generation data sets. 

In this example, an lEHPROGM job step, STEPA, creates a model DSCB and builds a 
generation index. STEPS, an lEBGENER job step, creates and catalogs a sequential 
generation from card input. 

The example follows: 

//BLDINDX JOB 

//STEPA EXEC PGM=IEHPROGM 
//SYSPRINT DD SYSOUT=A 

//BLDDSCB DD DSNAME=A.B.C,DISP=( ,KEEP ) , SPACE=( TRK, ) , 
// DCB=( LRECL=80 , RECFM=FB , BLKSIZE=800 ) , 
// V0LUME=SER=11 1 111 ,UNIT=2314 
* 

INDEX=A . B . C , ENTRIES= 1 , EMPTY , DELETE 

PGM=IEBGENER 

SYSOUT=A 

DUMMY 

DSNAME=A.B.C(+1 ) ,UNIT=23 1 4 ,DISP=( ,CATLG), 
// VOLUME=SER=231400,SPACE=( TRK, ( 20 ) ) 
//SYSUT1 DD DATA 

(input card data) 

/* 

The control statements are discussed below: 

• BLDDSCB DD creates a model DSCB on the system residence volume. 

• SYSIN DD indicates that a utility control statement (BLDG) is included next in the 
input stream. 

• BLDG specifies the generation group name A.B.C and makes provision for ten lower 
level entries in the index. When the 11th entry is to be entered, the index is 
emptied and all of the generations are deleted. 

• SYSUT2 DD defines an output sequential generation. The generation is assigned 
the absolute generation and version number GOOOIVOO in the index. 

• SYSUTl DD defines the input card data set. 

Any subsequent job that causes the deletion of the generations should include DD 
statements defining the devices on which the volumes containing those generations 
are to be mounted. Each generation for which no DD statement is included is 
uncataloged at that time, but not deleted. 

After the generation data group is emptied, new generations continue to be assigned 
generation numbers according to the last generation number assigned before the 
empty operation. To restart the numbering operation (that is, to reset to GOOOOVOO or 
GOOOIVOO), it is necessary to uncatalog all the old generation data sets and then 
rename and recatalog, beginning with GOOOOVOO. 



//SYSIN 


DD 




BLDG 


/* 




//STEPB 


EXEC 


//SYSPRINT 


DD 


//SYSIN 


DD 


//SYSUT2 


DD 
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Generation Example 2 



Generation Example 3 



JOB 

EXEC PGM=IEBGENER 

DD SYSOUT=A 

DD DUMMY 

DD DSNAME=A.B.C(+1 ) ,UNIT=2314,DISP=( , CATLG ) , 



In this example, a second generation is created and cataloged in the Index built in 
Example 1. DCB attributes are included to override those attributes that were 
specified when the model DSCB was created. 

The example follows: 

// 

// 

//SYSPRINT 

//SYSIN 

//SYSUT2 

// DCB={LRECL=80,RECFM=FB,BLKSIZE=1600 ), 

// VOLUME=SER=231401 ,SPACE=( TRK, ( 20 ) ) 

//SYSUT1 DD DATA 

(input data set) 

/* 

The control statements are discussed below: 

• SYSUT2 DD defines an output sequential generation. The generation is assigned 
the absolute generation and version number G0002V00 in the index. The specified 
DCB attributes override those initially specified in the model DSCB. The DCB 
attributes specified when the model DSCB was created remain unchanged; that is, 
those attributes are applicable when you catalog a succeeding generation unless 
you specify overriding attributes at that time. 

• SYSUTl DD defines the input card data set. 

In this example, a generation index for generation data group A.B.C is built. Three 
existing noncataloged, non-generation data sets are renamed; the renamed data sets 
are cataloged as generations in the generation index. 

The example follows: 



//BLDINDEX 

// 

//SYSPRINT 

//DD1 

//DD2 

// VOLUME=( 

//SYSIN 
BLDG 
RENAME 

RENAME 

RENAME 

CATLG 
CATLG 
CATLG 



JOB 

EXEC 

DD 

DD 

DD 



PGM=IEHPROGM 

SYSOUT=A 

UNIT=2314,VOLUME=SER=1 11111 ,DISP=OLD 

UNIT=( 2314, , DEFER ),DISP=OLD, 
PRIVATE , , SER=( 23 1 400 ) ) 
DD * 

INDEX=A . B . C , ENTRIES= 1 
DSNAME=DATASET1 , VOL=23 1 4=23 1 400 , 

NEWNAME=A . B . C . GOOO 1 VOO 
DSNAME=DATASET2 , VOL=23 1 4=23 1400, 

NEWNAME=A .B.C.G0002V00 
DSNAME=DATASET3 , VOL=23 1 4=23 1 400 , 

NEWNAME=A.B.C.G0003V00 
DSNAME=A. B.C. GOOO 1 VOO, VOL=23 14=23 1400 
DSNAME=A.B.C.G0002V00,VOL=23 14=23 1400 
DSNAME=A.B.C.G0003V00,VOL=23 14=23 1400 



nc 
lie 



/* 

The control statements are discussed below: 

• DDl DD defines the system residence volume, on which the SYSCTLG (system 
catalog) data set resides. 

• BLDG specifies the generation group name A.B.C and makes provision for ten 
entries in the index. The oldest generation is to be uncataloged when the index 
becomes full. No generations are to be scratched. 

• The RENAME statements rename three non-generation data sets residing on a 
2314 disk volume. 

• CATLG catalogs the renamed data sets in the generation index. 

Note: Because the DCB parameters were supplied when the non-generation data sets 
were created, no DCB parameters are now specified; therefore, no model DSCB is 
required. 
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Generation Example 4 



Generation Example 5 



JOB 

EXEC PGM=IEBCOPY 

DD SYSOUT=A 

DD DSNAME=A.B.C(-1 ),DISP=OLD 

DD DSNAME=TESTSET , UNIT=23 1 4 , DISP=( , KEEP ) , 



In this example, a non-generation version of a generation data set is to be made. The 
generation is represented as the next to latest entry in the index. The name of the 
resultant data set is TESTSET. This example assumes that the generation to be copied 
is partitioned. 

The example follows: 

//COPY 

// 

//SYSPRINT 

//SYSUT1 

//SYSUT2 

// VOLUME=SER=231400,SPACE=(TRK,( 20, 10,5 ) ), 

/// DCB=( RECFM=FB , LRECL=80 , BLKSIZE=80 ) 

//SYS IN DD DUMMY 

/* 

The control statements are discussed below: 

• SYSUTl DD defines the generation from which a copy is to be made. 

• SYSUT2 DD defines a partitioned data set (TESTSET) on a 2314 output volume. 
The DCB attributes in this statement are identical to those assigned to the 
generation. (Reblocking is permitted, but the SYSUT2 block size specification must 
be a multiple of the original block size.) 

In this example, a partitioned generation, consisting of three members, is to be used 
as source data in the creation of a new generation. lEBUPDTE is to be used to add a 
fourth member to the three source members and to number the new member. The 
resultant data set is to be cataloged as a new generation. 

The example follows: 



// 
// 



//SYSPRINT DD 
//SYSUTl DD 
//SYSUT2 DD 



JOB 

EXEC PGM=IEBUPDTE,PARM=MOD 



SYSOUT=A 

DSNAME=A. B . C( ) , DISP=OLD 

DSNAME=A.B.C(+1 )DISP=( , CATLG ) ,UNIT=2314 , 
// VOLUME=SER=231400,SPACE=(TRK,( 100,10, 10) ), 
// DCB=( RECFM=FB,LRECL=80,BLKSIZE=800 ) 



//SYSIN 

./ 

./ 

./ 

./ 

./ 



REPRO 

REPRO 

REPRO 

ADD 

NUMBER 



DD DATA 

NAME=MEM1 , LEVEL=00 , SOURCE=0 , LIST=ALL 
NAME=MEM2 , LEVEL=00 , SOURCE=0 , LIST=ALL 
NAME=MEM3 , LEVEL=00 , SOURCE=0 , LIST=ALL 
NAME=MEM4 , LEVEL=00 , SOURCE=0 , LIST=ALL, IGNORE=EOF 
NEW1=10,INCR=5 



(data cards comprising MEM4) 

. / ENDUP 
/* 

The control statements are discussed below: 

• SYSUTl DD defines the latest generation, which is used as source data. 

• SYSUT2 DD defines the new generation, which is created from the source 
generation and from an additional member included as input card data. 

• The REPRO Function statements reproduce the named source members in the 
output generation. 

• The ADD Function statement specifies that the data cards following the input 
stream be included as MEM4. 

• The NUMBER Detail statement indicates that the new member is to have sequence 
numbers assigned in columns 73 through 80. The first record is assigned sequence 
number 10. The sequence number of each successive record is incremented by 5. 

• ENDUP signals the end of input card data. 

Note: This example assumes that a model DSCB exists on the catalog volume on 
which the index was built. 
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Appendix E: Processing User Labels 



Processing User Labels 
as Data Set Descriptors 



User labels can be processed by lEBGENER, lEBCOMPR, lEBPTPCH, lEHMOVE, 
lEBCTRIN, and lEBUPDTE. In some cases, user-label processing is automatically 
performed; in other cases, you must indicate the processing to be performed. In 
general, user label support allows the utility program user to: 

• Process user labels as data set descriptors. 

• Process user labels as data. 

• Total the processed records prior to each WRITE command (lEBGENER and 
lEBUPDTE only). 

For either of the first two options, the user must specify standard labels (SUL) on the 
DO statement that defines each data set for which user-label processing is desired. 
For totaling routines, OPTCD = T must be specified on the DD statement. 

The user cannot update labels by means of the lEBUPDTE program. This function must 
be performed by a user's label processing routines. lEBUPDTE will, however, allow you 
to create labels on the output data set from data supplied in the input stream. See the 
discussion of the LABEL statement in the chapter "lEBUPDTE Program." 

lEHMOVE does not allow exits to user routines and does not recognize options 
concerning the processing of user labels as data. lEHMOVE always moves or copies 
user labels directly to a new data set. See the chapter "lEHMOVE Program." 

Volume switch labels of a multivolume data set cannot be processed by lEHMOVE, 
lEBGENER, or lEBUPDTE. Volume switch labels are therefore lost when these utilities 
create output data sets. To ensure that volume switch labels are retained, process 
multivolume data sets one volume at a time. 

When user labels are to be processed as data set descriptors, one of the user's 
label processing routines receives control for each user label of the specified type. 
The user's routine can include, exclude, or modify the user label. Processing of user 
labels as data set descriptors is indicated on an EXITS statement with keyword 
parameters that name the label processing routine to be used. 

The EXIT keyword parameters indicate that a user routine should receive control each 
time the OPEN, EOV, or CLOSE routine encounters a user label of the type specified. 

Figure 70 illustrates the action of the system at OPEN, EOV, or CLOSE time. When 
OPEN, EOV, or CLOSE recognizes a user label and when SUL has been specified on 
the DD statement for the data set, control is passed to the utility program. Then, if an 
exit has been specified for this type of label, the utility program passes control to the 
user routine. The user's routine processes the label and returns control, along with a 
return code, to the utility program. The utility program then returns control to OPEN, 
EOV, or CLOSE. 



OPEN/EOV/CLOSE 



Utility program 



Exiting to a User's 
Totaling Routine 



User's label 
processing routine 



Figure 70. System Action at OPEN, EOV, or CLOSE Time 



This cycle is repeated up to eight times, depending upon the number of user labels in 
the group and the return codes supplied by the user's routine. 

When an exit is taken to a user's totaling routine, an output record is passed to the 
user's routine just before the record is written. The first halfword of the totaling area 
pointed to by the parameter contains the length of the totaling area, and should not 
be used by the user's routine. If the user has specified user label exits, this totaling 
area (or an image of this area) is pointed to by the parameter list passed to the 
appropriate user label routine. 
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Processing User Labels 
as Data 



Note: An output record is defined as a physical record (block), except when lEBGENER 
is used to process and reformat a data set that contains spanned records. 

When user labels are processed as data, the group of user labels, as well as the 
data set, is subject to the normal processing done by the utility program. The user can 
have his labels printed or punched by lEBPTPCH, compared by lEBCOMPR, or copied 
by lEBGENER. 

To specify that user labels are to be processed as data, include a LABELS statement 
in the job step that is to process user labels as data. 

There is no direct relationship between the LABELS statement and the EXITS 
statement. Either or both can appear in the control statement stream for an execution 
of a utility program. If there are user label-processing routines, however, their return 
codes may influence the processing of the labels as data. In addition, a user's output 
label processing routine can override the action of a LABELS statement because it 
receives control before each output label is written. At this time the label created by 
the utility as a result of the LABEL statement is in the label buffer, and the user's 
routine can modify it. 

The code returned by the user's totaling routine determines system response as 
follows: 

• 0, which specifies that processing is to continue, but no further exits are to be 
taken. 

• 4, which specifies that normal processing is to continue. 

• 8, which specifies that processing is to terminate, except for EOD processing on 
tiie output data set (user label processing). 

• 16, which specifies that processing is to be terminated. 
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Index 



Indexes to systems reference library manuals are 
consolidated in IBM System/360 Operating System: 
Systems Reference Library Master Index, GC28-6644. For 
additional information about any subject listed below, 
refer to other publications listed for the same subject in 
the Master Index. 

Note: If more than one page number is given, the primary 
discussion is listed first. The entries in the index appear 
the same way they appear in the body of the book, which 
means that entries with bold type or italic type in the 
body of the book appear in bold type or italic type in the 
index. 

[] 7 

{ } . ■ . • 7 

A 

absolute generation and version number 289 

action on return codes 281 

action (lEBDG) 87 

ADD 168 

ADD statement 269 

adding data set passwords 262 

adding new member to a symbolic library 167 

ALIAS statement 

for lEBUPDAT 162 

for lEBUPDTE 174 

alias names 

listed by lEHLIST 218 

processed by lEBCOPY 53 

ALLOCATE module, changing or replacing 215 

allocating space 

with tiie lEBCOPY program 57 

with the lEHMOVE program 227,228,229 

alphameric tape labeling 209 

alternate DD names, specifying 283 

alternate tracks, assigning 

with IBCDASDI 27,30 

with lEHATLAS 185 

with lEHDASDR 189,198 

ANALYZE statement 194 

ANS volume labels 209,211 

ASCII labels 209 

assigning 

alternate tracks 

with IBCDASDI 27,30 

with lEHATLAS 185 

with lEHDASDR 189,198 

sequence numbers 171,172 

serial numbers (lEHDASDR) 195,197,198,199,201 

asterisk (*). in PDS directory entry 217 

ATTACH macro instruction 283 

attributes of DD statements defining mountable volumes . . 287 

B 

backup copy, producing a 

using lEBCOPY 53 

using lEBGENER 107 

using lEHDASDR 190 

bad VTOC, assigning alternate track for 185 

basic move and copy operations 230 

BDAM data set, moving or copying 230 

BLDA statement 268 

BLDG statement 269 

BLDX statement 267 

bold type, use of 7 

bootstrap records, construction of . . 189 

braces { }, use of 7 



brackets [ ], use of 7 

buffer 

FCB, loading of 43 

UCS, loading of 43 

building 

a generation data set 291 

a generation index 260,290 

an index 258 

an index alias 259 

bypassing defective-track checking feature 27,29,31 

c 

carriage control, specifying 133,135 

catalog 

building index in 258,260 

copying 233 

listing 217 

moving 233 

placing entries in 257 

cataloged data sets, punching 129 

cataloging 

a data set 257 

a generation data set 297 

a procedure 175 

with the lEHMOVE program 227 

with the lEHPROGM program 257 

cataloging moved or copied data, automatically 227 

CATLG statement 266 

CHANGE 168 

changing 

a volume serial number 190 

the logical record length of a data set 109 

the organization of a data set 165,107 

chart, utility program function 19 

checking for flagged defective tracks 

with the IBCDASDI program 27 

with the lEHDASDR program 189 

CLOSE module, changing or replacing 215 

COLUMN specification 170 

combinations of NEW, MEMBER, and NAME keywords . . .171 

comments, on utility control statements 24 

COMPARE statement 47 

comparing 

partitioned directories 45 

partitioned data sets 45 

records 45 

sequential data sets 45 

compatible volumes 228 

compatibility with respect to size, volume 228 

compress in place 55 

compressing a data set 55 

concatenating SYSIN data sets when using lEHDASDR . . . 193 
concurrent operations when using lEHDASDR, specifying . . 193 

CONNECT statement 268 

connecting two control volumes 259 

considerations 

for the MVT user 24 

for defining DD statements 287 

continuing utility controll statements 24 

control passwords 

adding 269 

deleting 271 

replacing 270 

control statements 

format of . 23 

restrictions 24 

control statements, subordinate 238 
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control volumes 

connecting 259 

copying 233 

disconnecting 259 

moving . 233 

controlling 

IBCDASDI 27 

IBCDMPRS 33 

IBCRCVRP 37 

ICAPRTBL 43 

lEBCOMPR 46 

lEBCOPY 56 

lEBDG 83 

lEBEDIT 101 

lEBGENER 109 

lEBISAM 125 

lEBPTPCH 130 

lEBTCRIN 149 

lEBUPDAT 159 

lEBUPDTE 166 

lEHATLAS 185 

lEHDASDR 192 

lEHINITT 210 

lEHIOSUP 215 

lEHLIST 220 

lEHMOVE 234 

lEHPROGM 263 

IFHSTATR 277 

conventions, notational 7 

converting a data set 

from partitioned to sequential organization .... 107,165 

from sequential to partitioned organization 165 

converting data 

from alphameric to hexadecimal 134,137 

from H-set BCD to EBCDIC 108,134,137 

from packed to unpacked decimal .... 108,114,134,137 

from unpacked to packed decimal 108 

COPY statement 58 

COPY CATALOG statement 244 

COPY DSGROUP statement 240 

COPY DSNAME statement 239 

copy operation 658,53 

COPY PDS statement 242 

COPY VOLUME statement 245 

copying 

a BDAM data set 230 

a catalog 233 

a data set 53,230 

a direct data set with variable spanned records 234 

a dumped data set 191 

a" group of data sets 232 

a partitioned data set 53,227,231 

a volume of data sets 233 

an indexed sequential data set 123,124 

members of a partitioned data set 53,227 

records of a sequential data set 107 

sequential data sets 53 

CREATE statement 89 

creating 

a backup copy 

using lEBCOPY 53 

using lEBGENER 107 

using lEHDASDR 190 

a generation Index 290 

a library 165 

a model DSCB 292 

a partitioned data set from sequential Input 107 

a sequential copy of an indexed sequential data set . . .123 

a sequential output data set 145 

a sequential output job stream 101 

an edited data set 107 

user labels on sequential output 107 



DADEF statement 28 

DASDI program (see IBCDASDI) 
data 

dumped • • ■ 191 

movable 228 

reconstructed 227,123 

recovering usable 37 

unloaded 227,123,124 

unmovable 227 

data set control block (DSCB), setting protection 

status In 261 

data set passwords 261,262,263 

adding 262,269 

deleting 262,271 

listing 269,272 

replacing 270 

data set utility programs 25 

lEBCOMPR 45 

lEBCOPY 53 

lEBDG 81 

lEBEDIT 101 

lEBGENER 107 

lEBISAM 123 

lEBPTPCH 129 

lEBTCRIN 145 

lEBUPDAT 159 

lEBUPDTE 165 

data sets 

cataloging 257 

compressing 55 

converting 107,165 

copying 53,230 

merging 55 

moving 230 

protecting 261 

reconstructing 55 

re-creating 257 

renaming 257 

scratching 257 

uncataloging 257 

unloading 227,123 

data sets, moving or copying a group of 232,233 

data sets, partitioned (see partitioned data sets) 

Data statement 173 

DD names, alternate 283 

DD statement, attributes 287 

DD statements, operational results of 287 

ddnameaddr 283 

deblocking with lEBCOPY 57 

defective track 

indicated by lEHATLAS 185 

indicated by data check 185 

indicated by missing address marker 185 

recovering data from 185,33 

testing for 189,27 

deferred mounting, specifying . 287 

deferred step restart with relative generation numbers . . . 290 
defining data sets 

with the lEBCOMPR program 46 

with the lEBCOPY program 56 

with the lEBDG program 81,82,83 

with the lEBEDIT program 101 
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defining mountable devices 287 

DFN 43 

DELET statement ! 161 

DELETE 171 

DELETER statement 271 

deleting 

a record 171,161 

an index 258 

an index alias 259 

data set passwords 271 

demounting mountable volumes 287 

Detail statement 171 

device name 24 

DFN statement 43 

direct access volumes 

assigning alternate tracks to 190,27,185 

dumping 373,198,199 

initializing 27,189 

restoring 33 

direct data set, moving or copying 230 

with variable spanned records 234 

directory entry, format of 212 

disconnecting volumes 259 

DLTA statement 268 

DLTX statement 267 

DSCB 

model for generation data sets 292 

setting protection status in 269,262 

DSD statement 85 
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DUMP statement 

for IBCDMPRS program 33 

for lEHDASDR program 198 

DUMP/RESTORE program (see IBCDMPRS) 

dumping a direct access volume 333,189,198 

dumping multiple volumes to a single restore tape 200 
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E 

EDIT statement 101 

edited format 

of aVTOC 219 

of a PDS directory entry 218 

editing 

a job stream 101 

data 145,148,101 

sequential data set 107 

partitioned data set 107 

editing facilities 

with the lEBGENER program 107 

with the lEBPTPCH program 130 

with the lEBTCRIN program 151 

ellipsis, use of 7 
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forlBCDASDI 31 

for IBCDMPRS 36 

forlBCRCVRP 41 

forlCAPRTBL 44 

for lEBDG 93 

end of cartridge 149 

end of file (EOF) record, assigning alternate track 187 

ENDUP statement 

for lEBUPDAT 162 

for lEBUPDTE 175 

ensuring volume integrity 287 

entering job control statements into a procedure library . . 176 

EOV module, changing or replacing 215 

ERROPT 152 

ERROR 153 
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format 277 

processing 277 
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lEHPROGM 272 
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FCB 
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FD statement 85 
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flagged defective tracks, checking for 189,27 
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forms control buffer, loading the 43,44 
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JOB . . 33 

MSG 33 

RESTORE 35 

VDRL 35 

IBCRCVRP program 37 

control of 37 

examples 41 

executing 26 



input and output 37 

introduction 25 

used to 

recover usable data 37 

replace bad data 37 

utility control statements 37 

END 41 

JOB 38 

INSERT 40 

LIST 40 

MSG 38 

RECOVER 38 
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control of 43 

example 44 

executing 26 

input and output 43 

introduction 25 

used to 

load forms control buffer 43 

load Universal Character Set buffer 43 

utility control statements 43 

DFN 43 
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lEBPTPCH program 129 

control of 130 

job control statements 130 

restrictions 131 

utility control statements 131 

examples 139 

input and output 130 

introduction 25 

region size 130 

return codes 130 

used to print or punch 

a partitioned directory 129 

an edited data set 130 

data sets . 129 

selected members 129 

selected records . 129 

utility control statements 131 

EXITS 136 

LABELS 138 

MEMBER 136 

PRINT 132 
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job control statements 166 
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ALIAS 174 

Data 173 

Detail 171 

ENDUP 175 

Function 167 

LABEL 173 
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job control statements 185 

restrictions 185 
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examples 187 
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restrictions 210 

utility control statement 211 

examples 212 
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job control statements 215 
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job control statements 220 
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examples 223 

input and output 220 
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utility control statements 221 
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lEHMOVE program 227 

control of 234 

job control statements 235 

for track overflow feature 237 
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utility control statements 237 

examples 248 

input and output 234 
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return codes 234 

used to move or copy 

a catalog 233 
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MOVE CATALOG 243 
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MOVE PDS 241 

MOVE VOLUME 245 

REPLACE 247 
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examples 272 
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catalog or uncatalog a data set 257 
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rename a data set or member 257 

replace data set passwords 262 

scratch a data set or member .257 

utility control statements 265 
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BLDA 268 

BLDG 269 

BLDX 267 

CATLG 266 

CONNECT 268 

DELETER 271 

DLTA 268 

DLTX 267 

LIST 272 

RELEASE 269 

RENAME 266 

REPLACE 270 

SCRATCH 265 

UNCATLG 267 

IFHSTATR program 277 

control of 277 

job control statements 278 

example 278 

input and output 277 

Introduction 24 
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use of 277 

INCLUDE statement 246 

including data in move and copy operations 227 

INDD statement 59 
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IBCDASDI 25 

IBCDMPRS 33 
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building 258,267 

create new 267 
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generation 289,290,269 
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building 259,268 

deleting 259,268 
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creating backup 123 
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printing 124 

unloading 123 

initializing direct access volumes 

with IBCDASDI 27 

with lEHDASDR 189 

with surface analysis 189 

without surface analysis 189 
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input stream, organizing 101 

input to and output from 
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IBCDMPRS 33 

IBCRCVRP 37 

ICAPRTBL 43 

lEBCOMPR 46 

lEBCOPY 55 

lEBDG 82 

lEBEDIT 101 
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lEBUPDTE 165 

lEHATLAS 185 
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lEHINITT 210 

lEHIOSUP 215 
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lEHPROGM 263 

IFHSTATR 277 
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inserting blocks of records 173,165 
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IPLTXT statement 

for IBCDASDI 30 

for lEHDASDR 201 

IPL program 195,197,201,28,30 
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lEBCOPY 56 
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lEBEDIT 101 

lEBGENER 110 

lEBISAM 125 
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lEBTCRIN 149 
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for IBCDASDI 27 

for IBCDMPRS 33 
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JOB steps, copying Ill 

job stream, organizing 101 
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keywords, combinations of NEW, MEMBER, and NAME 
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LABEL statement 

for lEBUPDTE 173 

for lEHDASDR 198 

label processing 

using lEBCOMPR 47 

using lEBGENER 112 

using lEBPTPCH 138 

using lEBTCRIN 154,155 

using lEBUPDTE 169 

using lEHMOVE 230 
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for lEBCOMPR 47 

for lEBGENER 112 
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labeling a magnetic tape volume .209 

LASTCARD statement 31 

levels of Index 

creating 258 

deleting 258 

libraries, updating symbolic . 165 

LINK macro instruction ............... 273,279 

linking to an exit routine • • ■ • 273 

LIST statement 

forlBCRCVRP 40 

for lEHPROGM 272 

listing 
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a partitioned data set 129 

a partitioned directory .............. 129,217 

a password entry 272 

a volume table of contents . 218 

catalog entries 217 

data set passwords . 272 

error statistics by volume (ESV) records . ... . . . .277 

system control data 217 

LISTCTLG statement 221 
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load operation, specified in PARM parameter . . . . . ... 126 

loading 

an indexed sequential data set . . . . . . , ... 123,124 

an unloaded data set . . . . 123 

forms control buffer 43 

Universal Character Set buffer 43 

logical record length, changing 109 

Logical Record statement • • ■ 162 
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magnetic tape volumes 

labeling .209 

moving or copying a group of data sets to ...... . .232 

moving or copying a volume of data to 233 

MEMBER, NEW, and NAME keywords, combinations of . . .171 
MEMBER statement 

for lEBGENER .113 

for lEBPTPCH 136 

members, partitioned, data set 

comparing . . . . . . . .... 45 

copying and merging . . . . . 53,227 

printing and punching ........ ..... .... 129 

renaming 257,227 

replacing 227 

scratching 257 

members of a symbolic library 
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replacing 227 

merge data sets . . . ... . . . . . . . 55 

methods of executing 

data set utility programs .... ..... :■■ . . . . . . 25 

independent utility programs 26 

system utility programs 24 
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mountable devices, defining 287 

MOVE CATALOG statement 243 

MOVE DSGROUP statement . . . .... . .239 

MOVE DSNAME statement .......... ... . . . 238 

MOVE PDS statement . . . . . 241 

MOVE VOLUME statement 245 

moving 

a BDAM data set 230 
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a data set 230 

a direct data set with variable spanned records ..... 234 
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a volume of data sets 233 

the SYSCTLG data set ...... 233 

moving and copying 

data 227 
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moving and copying operations 

excluding data from 55,61,246 

including data in . . . . . ... . . . . . . . . . . .246 

results of . . .... ... . . . . . . . . . . . 227,228 

selecting members for . 54,60,247 

moving or copying a password-protected volume 229 

moving the SVC library 230 

move vs. copy 227 
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forlBCDASDI 28 

forlBCDMPRS 33 

forlBCRCVRP . .... . . 38 

MTDI input 145 

MTST input . . . . .... . . . . . . . . 145 

multivolume data sets, moving or copying .227 

multiprogramming considerations 

with generation data groups . 292 

for MFT system . . . , ........ .287 

forMVTsystem ..;.....■...... . . . . 287,24 

new master data set ... . ... . ... . 165 

NEW, MEMBER, and NAME keywords, combinations of ... 171 
nonsharable attribute, assigning . ............ .287. 

nonsharable devices 287 

notation for defining control statements .7 

NUMBR statement . . . . .161 

numbering records in a partitioned data set 165,168 

numeric tape labeling . 209 

old master data set .................. . . 165 

OPEN module, changing or replacing . ... . . .... . 215 

operand field ...................... 23,24 

operating procedures for independent utilities . 26 

optionaddr 283,285 
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program. . . . . . . . . . . . . . . . ... . . 231,232 

organizing an input stream . . . . . . . . . . . .... . 101 

output from utility programs (see input to and output from) 
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packed to unpacked decimal conversion . . .108,114,134,137 

PARAM subparameter . .283 

parameters passed to exit routines 279 

for label processing 279 

for non-label processing . . 280 
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with the lEBDG program . ............... 84 

with the lEBISAM program . . . . . . ........ .125 

with the lEBUPDAT program 159 

with the lEBUPDTE program 167 

with the lEHDASDR program 193 

with the lEHINITT program 210 

with the lEHLIST program 221 

with the lEHMOVE program . 236 

with the lEHPROGM program .............. 265 

partial dumps of direct access volumes . ......... 198 

partitioned data sets 

comparing . . . . . . . 45 

compressing in place . 55 

converting to sequential 107,165 

copying 53,230 

copying selected members of 53,227 

editing 107 

expanding ....................... 107 

excluding from move and copy operations . . ... 61,246 

listing . . . . . . . . . . ............... 217 
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merging members of 61 

moving 230 

numbering records in 165,168 

produced from sequential input 165 

renaming 257 

replacing records in 54,165 

unloading 227 

updating in place 165 

partitioned data set directory entry, edited format . . 217,218 

PASSWORD data set 

adding entries to 269 

deleting entries from . .271 

listing entries in 272 

replacing entries in 270 

password-protected data sets, lEHDASDR 189 

password-protected volumes, moving or copying 229 

passwords, data set 

adding 269 

deleting 271 

listing 272 

replacing 270 

patterns of test data 81 

picture, user-specified 82 

prerequisite publications 6 

print specifications 

standard 129 

user 129 

PRINT statement 131 

printing 

a partitioned directory 129,217 

an edited data set 130 

data sets 129 

indexed sequential data sets 124 

logical records from an indexed sequential data set . . .124 

partitioned data sets 129 

selected records 129 

sequential data set 107,129 

private attribute, assigning 287 

procedure library, entering procedures in .176 

procedures 

cataloging 176 

program classes 

data set 25 

system 24 

independent 25 

program selection 19 

protecting data sets (see lEHPROGM utility program) 

public attribute, specifying 287 

punch specifications 

standard 129 

user 129 

PUNCH statement 134 

punching 

records 129,136 

partitioned data sets 129 

sequential data sets 129 

punctuation, in syntax 7 

purging unexpired data sets 

ANALYZE operation 194 

DUMP operation 198 

FORMAT operation 196 

RESTORE operation 200 

Q 

quick DASDI 27,189,196 

R 

read MTDI input 145 

read MTST input 145 

reader procedure, selecting 25 

rearranging data fields within a record 107 
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withlEBCOPY 57 

with lEBGENER 109 

with lEHMOVE 230 

RECORD statement 

for lEBGENER 113 

for lEBPTPCH 136 

record groups, assigning 107 

records 

adding 160,165,173,159 

assigning sequence numbers to 159,161,165,170 

comparing 45 

copying 107 

deleting 171 

error 145 

error statistics by volume 277 

ESV 277 

printing 129 

punching 129 

renumbering 165 

replacing 167,157,165,173 

RECOVER statement 38 

recovering data from defective tracks 27 

recovering usable data 37 

re-creating a data set 55 

region specifications 

lEBCOMPR 46 

lEBCOPY 56 

lEBDG 84 

lEBEDIT 101 

lEBGENER 110 

lEBISAM 126 

lEBPTPCH 130 

lEBTCRIN 149 

lEBUPDAT 159 

lEBUPDTE 166 

lEHATLAS 185 

lEHDASDR 192 

lEHINITT 210 

lEHIOSUP . 215 

lEHLIST 220 

lEHMOVE 235 

lEHPROGM 264 

IFHSTATR 278 

registers, contents of when linking 279 

relative generation numbers 290 

RELEASE statement 269 

releasing two volumes 259 

removable volumes, allocating 287 

removing 

entries from an index structure . 257 

member and alias names from a partitioned directory . 257 

RENAME statement 266 

renaming 

a data set 257 

a multivolume data set 273 

selected members 55,257,266 

renumbering 165 

REPEAT statement 92 

REPL 168 

REPLACE statement 

forlBCRCVRP 39 

for lEHMOVE 247 

for lEHPROGM 270 

replacement data records 159,165,173 

replacing 

bad data 37 

data set passwords 270 

identically named members 54 

members in move and copy operations 227,53,54 

members of a symbolic library 165 

records in a partitioned data set 54,165 

selected members 55 
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REPRO 168 

reproducing members of a symbolic library 159,165 

required publications 6 

requirements, job control statement . 23 

RESTORE statement 

forlBCDMPRS 35 

for lEHDASDR 200 

restoring data to a direct access volume 33,200 

RETURN macro instruction . 280 

return codes 

for lEBCOMPR 46 

forlEBCOPY 56 

for lEBDG 83 

forlEBEDIT 101 

for lEBGENER 109 

forlEBISAM . 125 

forlEBPTPCH 130 

for lEBUPDTE 165 

for lEHDASDR 191 

forlEHINITT. . 210 

forlEHIOSUP . 215 

for lEHLIST 220 

forlEHMOVE 234 

forlEHPROGM 263 

return codes, action on . 280 

returning from an exit routine 280 

s 

SCRATCH module, changing or replacing 215 

SCRATCH statement .265 

scratching 

a data set 257 

a member 257 

a volume table of contents 257,265 

temporary data sets 257,265 

secondary passwords 262 

adding 269 

deleting 271 

replacing 270 

SELECT statement 

forlEBCOPY . 60 

for lEHMOVE 247 

selecting a program 19 

selecting members to be moved or copied 54 

selective 

copy 60 

rename 55 

replace 60 

sequence numbers, assigning 165 

sequential data sets 

comparing 45 

compressing 55 

converting to partitioned 159,165 

copying 53 

creating 123,145,101 

editing 145,148,101 

printing 107,129,130 

punching 129,130 

unloaded 123 

unloading 227 

sequential output job stream, creating . . ... 101 

sharing mountable devices ..... . . .287 

simultaneous lEHDASDR operations 193 

SOR . . . . . 145 

space allocation with lEBCOPY 57 

specific request for mountable volumes . 287 

specific volumes, making requests for . .... . 287 

specifying an expiration date . . . ... . . . . .... .236 

spill data sets, used with lEBCOPY . 57 

standard print operation 129 

standard punch operation . • • • • 129 

straight copy 54 

summary of major changes 17 

supplying literal information 7 



surface analysis of direct access volumes 189,194,27 

SVC library, moving 215 

symbolic libraries, updating 165 

SYSCTLG data set 

creating 266 

moving or copying 233 

system control data, listing 217 

system status information 170 

system utility programs 24 

lEHATLAS 185 

lEHDASDR 189 

lEHINITT 209 

lEHIOSUP 215 

lEHLIST 217 

lEHMOVE 227 

lEHPROGM . 257 

IFHSTATR 277 

T 

tape volumes, labeling 209 

tapemark in a volume label set 209 

TCLOSE module, changing or replacing 215 

TCRGEN statement 151 

temporary data sets, scratching 265 

temporary spill data sets 57 

test data 

generating 81 

patterns of 81 

TITLE statement 135 

TRACK statement 186 

track overflow feature 

with lEHATLAS 186 

with lEHMOVE 237 

tracks, getting alternate . . . . ' 27,185,189 

transfer control tables, updating 215 

TTR entries, updating 215 

TYPE 151 

type 21 record processing 277 

u 

ucs 

loading of 43 

statement 43 

uncataloging a data set 257 

UNCATLG statement 267 

underscore, use of 7 

unexpired data sets encountered 

during ANALYZE operation 195 

during DUMP operation 200 

during FORMAT operation 197 

during RESTORE operation 201 

Universal Character Set buffer, loading the 43 

unloaded data 123 

unloaded data sets 

creating 123 

loading 123,124 

reconstructing 123 

format of (lEBISAM) 124 

unloading 

indexed sequential data set 123 

partitioned data set 227 

sequential data set 227 

unmovable data sets, moving or copying 227 

unpacked to packed decimal conversion 114,115 

updating 

symbolic libraries 165 

transfer control tables 215 

TTR entries in the SVC library 215 

updating in place, a partitioned data set 165 

user exits (see exits) 
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user labels 

as data 298 

as data set descriptors 297 

copying 230 

EXITS statement 47,111,136,153 

LABEL statement 

LABELS statement 47,112,138 

linkage with label processing exit routines 297 

moving 230 

parameter lists of exit routines 279 

RECORD statement 113 

relationship between EXITS and LABELS 298 

return codes from exit routines 298 

utility program handling of 297 

volume switch labels 297 

with lEBCOMPR 47 

withlEBGENER 112 

with lEBPTPCH 138 

with lEBUPDTE 173 

with lEHMOVE 230 

user print specifications 129 

user punch specifications 129 

user-supplied picture 82 

using NEW, MEMBER, and NAME keywords 171 

utility control statements, format of 23 

utility control statements (IBCDASDI) 27 

DADEF 27 

END 28 

GETALT 28 

IPLTXT 28 

JOB 27 

LASTCARD 28 

MSG 28 

VLD 28 

VTOCD 28 

utility control statements (IBCDMPRS) 33 

DUMP 33 

END 36 

JOB 33 

MSG 33 

RESTORE 35 

VDRL 35 

utility control statements (IBCRCVRP) 37 

END 41 

INSERT 40 

JOB 38 

LIST 40 

MSG 38 

RECOVER 38 

REPLACE 39 

utility control statements (ICAPRTBL) 43 

DFN 43 

END 44 

FOB 44 

JOB 43 

UCS 43 

utility control statements (lEBCOMPR) 46 

COMPARE 46 

EXITS 46 

LABELS 46 

utility control statements (lEBCOPY) 58 

COPY 58 

EXCLUDE 61 

INDD 59 

SELECT 60 

utility control statements (lEBDG) 85 

CREATE 89 

DSD 85 

END 92 

FD 85 

REPEAT 92 

utility control statements (lEBEDIT) 101 

EDIT 101 



utility control statements (lEBGENER) Ill 

EXITS Ill 

GENERATE Ill 

LABELS 112 

MEMBER 113 

RECORD 113 

utility control statements (lEBPTPCH) 131 

EXITS 136 

LABELS 138 

MEMBER 136 

PRINT 132 

PUNCH 134 

RECORD 136 

TITLE 135 

utility control statements (lEBTCRIN) 150 

EXITS 153 

TCRGEN 151 

utility control statements (lEBUPDAT) 160 

ALIAS 162 

DELET 161 

ENDUP 162 

Header 160 

Logical Record 162 

NUMBR 161 

utility control statements (lEBUPDTE) 167 

ALIAS 174 

Data 173 

Detail .171 

ENDUP 175 

Function 167 

LABEL 173 

utility control statement (lEHATLAS) . 186 

TRACK or VTOC 186 

utility control statements (lEHDASDR) 194 

ANALYZE 194 

DUMP 198 

FORMAT 196 

GETALT 198 

IPLTXT 201 

LABEL 198 

RESTORE 200 

utility control statement (lEHINITT) 211 

INITT 211 

utility control statements (lEHLIST) 221 

LISTCTLG 221 

LISTPDS 222 

LISTVTOC 222 

utility control statements (lEHMOVE) 237 

COPY CATALOG 244 

COPY DSGROUP 240 

COPY DSNAME 239 

COPY PDS 242 

COPY VOLUME 245 

EXCLUDE 246 

INCLUDE 246 

MOVE CATALOG 243 

MOVE DSGROUP 239 

MOVE DSNAME 238 

MOVE PDS 241 

MOVE VOLUME 245 

REPLACE 247 

SELECT 247 

utility control statements (lEHPROGM) 265 

ADD 269 

BLDA 268 

BLDG 269 

BLDX 267 

CATLG 266 

CONNECT 268 

DELETEP 271 

DLTA 268 

DLTX 267 

LIST 272 

RELEASE 269 
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RENAME 266 volume serial number, changing 190 

REPLACE 270 volume switch labels, processing 297 

SCRATCH 265 volume table of contents 

UNCATLG 267 listing 218 

utility programs scratching 265 

functions of 19 volumes 

invocation of from a problem program 283 copying 232 

mounting and demounting 287 

V moving 232 

VDRL statement 35 VTOC, see volume table of contents 

verify VTOC entries/track, by device type 

backup copies 45 VTOC statement 186 

portions of records 45 VTOCD statement 30 

VLD statement 29 

volume compatibility with respect to size 228 W 

volume integrity, ensuring .287 3211 

volume label set " loading forms control buffer for 43,44 

contents of 209 loading Universal Character Set buffer for 43 

placing on magnetic tape 209 
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